resplite 1.2.0 → 1.2.2

package/README.md

@@ -87,7 +87,7 @@ OK
 
 ### Standalone server script (fixed port)
 
-Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process receives SIGINT (Ctrl+C) or SIGTERM; then it closes the server and exits cleanly.
+Run this as a persistent background process (`node server.js`). RESPLite will listen on port 6380 and stay up until the process receives SIGINT (Ctrl+C) or SIGTERM; then it closes the server and exits cleanly. If you kill the process (e.g. SIGKILL or force quit), all client connections are closed as well — with the default configuration the server runs in the same process, so when the process exits the TCP server and its connections are torn down.
 
 ```javascript
 // server.js
@@ -96,13 +96,6 @@ import { createRESPlite } from 'resplite/embed';
 const srv = await createRESPlite({ port: 6380, db: './data.db' });
 console.log(`RESPLite listening on ${srv.host}:${srv.port}`);
 
-async function shutdown() {
-  await srv.close();
-  process.exit(0);
-}
-
-process.on('SIGINT', shutdown);
-process.on('SIGTERM', shutdown);
 ```
 
 Then connect from any other script or process:
@@ -181,6 +174,212 @@ const srv = await createRESPlite({
 | `onCommandError` | A command failed (wrong type, invalid args, or handler threw). |
 | `onSocketError` | The connection socket emitted an error (e.g. `ECONNRESET`). |
 
+## Migration from Redis
+
+RESPLite is a good fit for migrating **non-replicated Redis** instances that have **grown large** (e.g. tens of GB) and where RESPLite's latency is acceptable. The SPEC_F flow (dirty-key tracker, bulk import, cutover) is designed for that scenario with minimal downtime.
+
+Migration supports two modes:
+
+### Simple one-shot import (legacy)
+
+For small datasets or when downtime is acceptable:
+
+```bash
+# Default: redis://127.0.0.1:6379 → ./data.db
+npm run import-from-redis -- --db ./migrated.db
+
+# Custom Redis URL
+npm run import-from-redis -- --db ./migrated.db --redis-url redis://127.0.0.1:6379
+
+# Or host/port
+npm run import-from-redis -- --db ./migrated.db --host 127.0.0.1 --port 6379
+
+# Optional: PRAGMA template for the target DB
+npm run import-from-redis -- --db ./migrated.db --pragma-template performance
+```
+
+### Redis with authentication
+
+Migration supports Redis instances protected by a password. Use a Redis URL that includes the password (or username and password for Redis 6+ ACL):
+
+- **Password only:** `redis://:PASSWORD@host:port`
+- **Username and password:** `redis://username:PASSWORD@host:port`
+
+Examples:
+
+```bash
+# One-shot import from authenticated Redis
+npm run import-from-redis -- --db ./migrated.db --redis-url "redis://:mysecret@127.0.0.1:6379"
+
+# SPEC_F flow: use --from with the full URL (or set RESPLITE_IMPORT_FROM)
+npx resplite-import preflight --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
+npx resplite-dirty-tracker start --run-id run_001 --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
+```
+
+For one-shot import, authentication is only available when using `--redis-url`; the `--host` / `--port` options do not support a password.
+
+### Minimal-downtime migration (SPEC_F)
+
+For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the migration runs online and only a short cutover is needed.
+
+**Enable keyspace notifications in Redis** (required for the dirty-key tracker). Either run at runtime:
+
+```bash
+redis-cli CONFIG SET notify-keyspace-events KEA
+```
+
+Or add to `redis.conf` and restart Redis:
+
+```
+notify-keyspace-events KEA
+```
+
+(`K` = keyspace prefix, `E` = keyevent prefix, `A` = all event types — lets the tracker see every key change and expiration.)
+
+> **Renamed CONFIG command?** Some Redis deployments rename `CONFIG` for security. Pass `--config-command <name>` to the CLI tools, or the `configCommand` option to the JS API — see below.
+
+1. **Preflight** – Check Redis, key count, type distribution, and that keyspace notifications are enabled:
+   ```bash
+   npx resplite-import preflight --from redis://10.0.0.10:6379 --to ./resplite.db
+   ```
+
+2. **Start dirty-key tracker** – Captures keys modified during bulk (requires `notify-keyspace-events` in Redis):
+   ```bash
+   npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db
+   # If CONFIG was renamed:
+   npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db --config-command MYCONFIG
+   ```
+
+3. **Bulk import** – SCAN and copy all keys; progress is checkpointed and resumable (resume is default; re-run the same command to continue after a stop):
+   ```bash
+   npx resplite-import bulk --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db \
+     --scan-count 1000 --max-rps 2000 --batch-keys 200 --batch-bytes 64MB
+   ```
+
+4. **Monitor** – Check run and dirty-key counts:
+   ```bash
+   npx resplite-import status --run-id run_001 --to ./resplite.db
+   ```
+
+5. **Cutover** – Freeze app writes to Redis, then apply remaining dirty keys:
+   ```bash
+   npx resplite-import apply-dirty --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db
+   ```
+
+6. **Stop tracker and switch** – Stop the tracker and point clients to RespLite:
+   ```bash
+   npx resplite-dirty-tracker stop --run-id run_001 --to ./resplite.db
+   ```
+
+7. **Verify** – Optional sampling check between Redis and destination:
+   ```bash
+   npx resplite-import verify --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db --sample 0.5%
+   ```
+
+Then start RespLite with the migrated DB: `RESPLITE_DB=./resplite.db npm start`.
+
+### Programmatic migration API (JavaScript)
+
+As an alternative to the CLI, the full migration flow is available as a JavaScript API via `resplite/migration`. Useful for embedding the migration inside your own scripts or automation pipelines.
+
+```javascript
+import { createMigration } from 'resplite/migration';
+
+const m = createMigration({
+  from:  'redis://127.0.0.1:6379',  // source Redis URL (default)
+  to:    './resplite.db',           // destination SQLite DB path (required)
+  runId: 'my-migration-1',          // unique run ID (required for bulk/status/applyDirty)
+
+  // optional — same defaults as the CLI:
+  scanCount:      1000,
+  batchKeys:      200,
+  batchBytes:     64 * 1024 * 1024,  // 64 MB
+  maxRps:         0,                  // 0 = unlimited
+  pragmaTemplate: 'default',
+
+  // If your Redis deployment renamed CONFIG for security:
+  // configCommand: 'MYCONFIG',
+});
+
+// Step 0 — Preflight: inspect Redis before starting
+const info = await m.preflight();
+console.log('keys (estimate):', info.keyCountEstimate);
+console.log('type distribution:', info.typeDistribution);
+console.log('notify-keyspace-events:', info.notifyKeyspaceEvents);
+console.log('CONFIG available:', info.configCommandAvailable);  // false if renamed
+console.log('recommended params:', info.recommended);
+
+// Step 0b — Enable keyspace notifications (required for dirty-key tracking)
+// Reads the current value and merges the new flags — existing flags are preserved.
+const ks = await m.enableKeyspaceNotifications();
+// → { ok: true, previous: '', applied: 'KEA' }
+// If CONFIG is renamed and configCommand was not set, ok=false and error explains how to fix it.
+
+// Step 1 — Bulk import (checkpointed, resumable). Same script to start or continue.
+await m.bulk({
+  onProgress: (r) => console.log(
+    `scanned=${r.scanned_keys} migrated=${r.migrated_keys} errors=${r.error_keys}`
+  ),
+});
+
+// Check status at any point (synchronous, no Redis needed)
+const { run, dirty } = m.status();
+console.log('bulk status:', run.status, '— dirty counts:', dirty);
+
+// Step 2 — Apply dirty keys that changed in Redis during bulk
+await m.applyDirty();
+
+// Step 3 — Verify a sample of keys match between Redis and the destination
+const result = await m.verify({ samplePct: 0.5, maxSample: 10000 });
+console.log(`verified ${result.sampled} keys — mismatches: ${result.mismatches.length}`);
+
+// Disconnect Redis when done
+await m.close();
+```
+
+**Resume automático (por defecto)**  
+`resume` viene en `true` por defecto. Da igual si es la primera vez o una reanudación: el mismo script sirve para empezar y para continuar. La primera ejecución arranca desde cursor 0; si el proceso se corta (Ctrl+C, crash, etc.), al volver a ejecutar el script continúa desde el último checkpoint. No hace falta pasar `resume: false` la primera vez ni cambiar nada para reanudar.
+
+The dirty-key tracker (to capture writes during bulk) still runs as a separate process via `npx resplite-dirty-tracker`. The API above handles everything else in a single script.
+
+#### Renamed CONFIG command
+
+If your Redis instance has the `CONFIG` command renamed (a common hardening practice), pass the new name to `createMigration`:
+
+```javascript
+const m = createMigration({
+  from: 'redis://10.0.0.10:6379',
+  to:   './resplite.db',
+  runId: 'run_001',
+  configCommand: 'MYCONFIG',  // the renamed command
+});
+
+// preflight will use MYCONFIG GET notify-keyspace-events
+const info = await m.preflight();
+// info.configCommandAvailable → false if the name is wrong
+
+// enableKeyspaceNotifications will use MYCONFIG SET notify-keyspace-events KEA
+const result = await m.enableKeyspaceNotifications({ value: 'KEA' });
+```
+
+The same flag is available in the CLI:
+
+```bash
+npx resplite-dirty-tracker start --run-id run_001 --to ./resplite.db \
+  --from redis://10.0.0.10:6379 --config-command MYCONFIG
+```
+
+#### Low-level re-exports
+
+If you need more control, the individual functions and registry helpers are also exported:
+
+```javascript
+import {
+  runPreflight, runBulkImport, runApplyDirty, runVerify,
+  getRun, getDirtyCounts, createRun, setRunStatus, logError,
+} from 'resplite/migration';
+```
+
 ### Strings, TTL, and key operations
 
 ```javascript
@@ -383,210 +582,6 @@ RESPLite implements **47 core Redis commands** (~19% of the ~246 commands in Red
 
 Unsupported commands return: `ERR command not supported yet`.
 
-## Migration from Redis
-
-RESPLite is a good fit for migrating **non-replicated Redis** instances that have **grown large** (e.g. tens of GB) and where RESPLite’s latency is acceptable. The SPEC_F flow (dirty-key tracker, bulk import, cutover) is designed for that scenario with minimal downtime.
-
-Migration supports two modes:
-
-### Simple one-shot import (legacy)
-
-For small datasets or when downtime is acceptable:
-
-```bash
-# Default: redis://127.0.0.1:6379 → ./data.db
-npm run import-from-redis -- --db ./migrated.db
-
-# Custom Redis URL
-npm run import-from-redis -- --db ./migrated.db --redis-url redis://127.0.0.1:6379
-
-# Or host/port
-npm run import-from-redis -- --db ./migrated.db --host 127.0.0.1 --port 6379
-
-# Optional: PRAGMA template for the target DB
-npm run import-from-redis -- --db ./migrated.db --pragma-template performance
-```
-
-### Redis with authentication
-
-Migration supports Redis instances protected by a password. Use a Redis URL that includes the password (or username and password for Redis 6+ ACL):
-
-- **Password only:** `redis://:PASSWORD@host:port`
-- **Username and password:** `redis://username:PASSWORD@host:port`
-
-Examples:
-
-```bash
-# One-shot import from authenticated Redis
-npm run import-from-redis -- --db ./migrated.db --redis-url "redis://:mysecret@127.0.0.1:6379"
-
-# SPEC_F flow: use --from with the full URL (or set RESPLITE_IMPORT_FROM)
-npx resplite-import preflight --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
-npx resplite-dirty-tracker start --run-id run_001 --from "redis://:mysecret@10.0.0.10:6379" --to ./resplite.db
-```
-
-For one-shot import, authentication is only available when using `--redis-url`; the `--host` / `--port` options do not support a password.
-
-### Minimal-downtime migration (SPEC_F)
-
-For large datasets (~30 GB), use the Dirty Key Registry flow so the bulk of the migration runs online and only a short cutover is needed.
-
-**Enable keyspace notifications in Redis** (required for the dirty-key tracker). Either run at runtime:
-
-```bash
-redis-cli CONFIG SET notify-keyspace-events KEA
-```
-
-Or add to `redis.conf` and restart Redis:
-
-```
-notify-keyspace-events KEA
-```
-
-(`K` = keyspace prefix, `E` = keyevent prefix, `A` = all event types — lets the tracker see every key change and expiration.)
-
-> **Renamed CONFIG command?** Some Redis deployments rename `CONFIG` for security. Pass `--config-command <name>` to the CLI tools, or the `configCommand` option to the JS API — see below.
-
-1. **Preflight** – Check Redis, key count, type distribution, and that keyspace notifications are enabled:
-   ```bash
-   npx resplite-import preflight --from redis://10.0.0.10:6379 --to ./resplite.db
-   ```
-
-2. **Start dirty-key tracker** – Captures keys modified during bulk (requires `notify-keyspace-events` in Redis):
-   ```bash
-   npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db
-   # If CONFIG was renamed:
-   npx resplite-dirty-tracker start --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db --config-command MYCONFIG
-   ```
-
-3. **Bulk import** – SCAN and copy all keys; progress is checkpointed and resumable:
-   ```bash
-   npx resplite-import bulk --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db \
-     --scan-count 1000 --max-rps 2000 --batch-keys 200 --batch-bytes 64MB --resume
-   ```
-
-4. **Monitor** – Check run and dirty-key counts:
-   ```bash
-   npx resplite-import status --run-id run_001 --to ./resplite.db
-   ```
-
-5. **Cutover** – Freeze app writes to Redis, then apply remaining dirty keys:
-   ```bash
-   npx resplite-import apply-dirty --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db
-   ```
-
-6. **Stop tracker and switch** – Stop the tracker and point clients to RespLite:
-   ```bash
-   npx resplite-dirty-tracker stop --run-id run_001 --to ./resplite.db
-   ```
-
-7. **Verify** – Optional sampling check between Redis and destination:
-   ```bash
-   npx resplite-import verify --run-id run_001 --from redis://10.0.0.10:6379 --to ./resplite.db --sample 0.5%
-   ```
-
-Then start RespLite with the migrated DB: `RESPLITE_DB=./resplite.db npm start`.
-
-### Programmatic migration API
-
-As an alternative to the CLI, the full migration flow is available as a JavaScript API via `resplite/migration`. Useful for embedding the migration inside your own scripts or automation pipelines.
-
-```javascript
-import { createMigration } from 'resplite/migration';
-
-const m = createMigration({
-  from:  'redis://127.0.0.1:6379',  // source Redis URL (default)
-  to:    './resplite.db',           // destination SQLite DB path (required)
-  runId: 'my-migration-1',          // unique run ID (required for bulk/status/applyDirty)
-
-  // optional — same defaults as the CLI:
-  scanCount:      1000,
-  batchKeys:      200,
-  batchBytes:     64 * 1024 * 1024,  // 64 MB
-  maxRps:         0,                  // 0 = unlimited
-  pragmaTemplate: 'default',
-
-  // If your Redis deployment renamed CONFIG for security:
-  // configCommand: 'MYCONFIG',
-});
-
-// Step 0 — Preflight: inspect Redis before starting
-const info = await m.preflight();
-console.log('keys (estimate):', info.keyCountEstimate);
-console.log('type distribution:', info.typeDistribution);
-console.log('notify-keyspace-events:', info.notifyKeyspaceEvents);
-console.log('CONFIG available:', info.configCommandAvailable);  // false if renamed
-console.log('recommended params:', info.recommended);
-
-// Step 0b — Enable keyspace notifications (required for dirty-key tracking)
-// Reads the current value and merges the new flags — existing flags are preserved.
-const ks = await m.enableKeyspaceNotifications();
-// → { ok: true, previous: '', applied: 'KEA' }
-// If CONFIG is renamed and configCommand was not set, ok=false and error explains how to fix it.
-
-// Step 1 — Bulk import (checkpointed, resumable)
-await m.bulk({
-  resume: false,                            // true to resume a previous run
-  onProgress: (r) => console.log(
-    `scanned=${r.scanned_keys} migrated=${r.migrated_keys} errors=${r.error_keys}`
-  ),
-});
-
-// Check status at any point (synchronous, no Redis needed)
-const { run, dirty } = m.status();
-console.log('bulk status:', run.status, '— dirty counts:', dirty);
-
-// Step 2 — Apply dirty keys that changed in Redis during bulk
-await m.applyDirty();
-
-// Step 3 — Verify a sample of keys match between Redis and the destination
-const result = await m.verify({ samplePct: 0.5, maxSample: 10000 });
-console.log(`verified ${result.sampled} keys — mismatches: ${result.mismatches.length}`);
-
-// Disconnect Redis when done
-await m.close();
-```
-
-The dirty-key tracker (to capture writes during bulk) still runs as a separate process via `npx resplite-dirty-tracker`. The API above handles everything else in a single script.
-
-#### Renamed CONFIG command
-
-If your Redis instance has the `CONFIG` command renamed (a common hardening practice), pass the new name to `createMigration`:
-
-```javascript
-const m = createMigration({
-  from: 'redis://10.0.0.10:6379',
-  to:   './resplite.db',
-  runId: 'run_001',
-  configCommand: 'MYCONFIG',  // the renamed command
-});
-
-// preflight will use MYCONFIG GET notify-keyspace-events
-const info = await m.preflight();
-// info.configCommandAvailable → false if the name is wrong
-
-// enableKeyspaceNotifications will use MYCONFIG SET notify-keyspace-events KEA
-const result = await m.enableKeyspaceNotifications({ value: 'KEA' });
-```
-
-The same flag is available in the CLI:
-
-```bash
-npx resplite-dirty-tracker start --run-id run_001 --to ./resplite.db \
-  --from redis://10.0.0.10:6379 --config-command MYCONFIG
-```
-
-#### Low-level re-exports
-
-If you need more control, the individual functions and registry helpers are also exported:
-
-```javascript
-import {
-  runPreflight, runBulkImport, runApplyDirty, runVerify,
-  getRun, getDirtyCounts, createRun, setRunStatus, logError,
-} from 'resplite/migration';
-```
-
 ## Scripts
 
 | Script | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/src/cli/resplite-import.js

@@ -47,6 +47,8 @@ function parseArgs(argv = process.argv.slice(2)) {
       }
     } else if (arg === '--resume') {
       args.resume = true;
+    } else if (arg === '--no-resume') {
+      args.resume = false;
     } else if (arg === '--pragma-template' && argv[i + 1]) {
       args.pragmaTemplate = argv[++i];
     } else if (arg === '--sample' && argv[i + 1]) {
@@ -120,7 +122,7 @@ async function cmdBulk(args) {
       max_rps: args.maxRps || 0,
       batch_keys: args.batchKeys || 200,
       batch_bytes: args.batchBytes || 64 * 1024 * 1024,
-      resume: !!args.resume,
+      resume: args.resume !== false, // default true: start from 0 or continue from checkpoint
       onProgress: (r) => {
         console.log(`  scanned=${r.scanned_keys} migrated=${r.migrated_keys} skipped=${r.skipped_keys} errors=${r.error_keys} cursor=${r.scan_cursor}`);
       },
@@ -210,7 +212,7 @@ async function main() {
     console.error('  --max-rps N          (bulk, apply-dirty)');
     console.error('  --batch-keys N       (default 200)');
     console.error('  --batch-bytes N[MB|KB|GB] (default 64MB)');
-    console.error('  --resume             (bulk: resume from checkpoint)');
+    console.error('  --resume / --no-resume  (bulk: default resume=on; use --no-resume to always start from 0)');
     console.error('  --sample 0.5%        (verify, default 0.5%)');
     process.exit(1);
   }

package/src/embed.js

@@ -35,6 +35,7 @@ export { handleConnection, createEngine, openDb };
  * @param {number} [options.port=0]               Port to listen on (0 = OS-assigned).
  * @param {string} [options.pragmaTemplate='default'] PRAGMA preset (default|performance|safety|minimal|none).
  * @param {RESPliteHooks} [options.hooks]         Optional event hooks for observability (onUnknownCommand, onCommandError, onSocketError).
+ * @param {boolean} [options.gracefulShutdown=true] If true, register SIGTERM/SIGINT to call close(). Set false if you handle shutdown yourself to avoid double handlers.
  * @returns {Promise<{ port: number, host: string, close: () => Promise<void> }>}
  */
 export async function createRESPlite({
@@ -43,6 +44,7 @@ export async function createRESPlite({
   port = 0,
   pragmaTemplate = 'default',
   hooks = {},
+  gracefulShutdown = true,
 } = {}) {
   const db = openDb(dbPath, { pragmaTemplate });
   const engine = createEngine({ db });
@@ -71,6 +73,14 @@ export async function createRESPlite({
     return closePromise;
   };
 
+  if (gracefulShutdown) {
+    const onSignal = () => {
+      close().then(() => process.exit(0));
+    };
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
+  }
+
   return {
     port: server.address().port,
     host,

package/src/index.js

@@ -1,5 +1,9 @@
 /**
  * RESPLite entry point. Start TCP server with SQLite backend.
+ *
+ * Can be run as CLI (node src/index.js) or used programmatically:
+ *   import { startServer } from './src/index.js';
+ *   startServer({ port: 6380, gracefulShutdown: false });
  */
 
 import { createServer } from './server/tcp-server.js';
@@ -15,23 +19,57 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_DB_PATH = path.join(process.cwd(), 'data.db');
 const DEFAULT_PORT = 6379;
 
-const dbPath = process.env.RESPLITE_DB || DEFAULT_DB_PATH;
-const port = parseInt(process.env.RESPLITE_PORT || String(DEFAULT_PORT), 10);
-const pragmaTemplate = process.env.RESPLITE_PRAGMA_TEMPLATE || 'default';
-
-const db = openDb(dbPath, { pragmaTemplate });
-const cache = createCache({ enabled: true });
-const engine = createEngine({ db, cache });
-const sweeper = createExpirationSweeper({
-  db,
-  clock: () => Date.now(),
-  sweepIntervalMs: 1000,
-  maxKeysPerSweep: 500,
-});
-sweeper.start();
-
-const server = createServer({ engine, port });
-
-server.listen(port, () => {
-  console.log(`RESPLite listening on port ${port}, db: ${dbPath}`);
-});
+/**
+ * @param {object} [options]
+ * @param {number} [options.port]
+ * @param {string} [options.dbPath]
+ * @param {string} [options.pragmaTemplate]
+ * @param {boolean} [options.gracefulShutdown=true] If true, register SIGTERM/SIGINT to close server and DB. Set false if you handle shutdown yourself.
+ */
+export function startServer(options = {}) {
+  const dbPath = options.dbPath ?? process.env.RESPLITE_DB ?? DEFAULT_DB_PATH;
+  const port = options.port ?? parseInt(process.env.RESPLITE_PORT || String(DEFAULT_PORT), 10);
+  const pragmaTemplate = options.pragmaTemplate ?? process.env.RESPLITE_PRAGMA_TEMPLATE ?? 'default';
+  const gracefulShutdown = options.gracefulShutdown !== false;
+
+  const db = openDb(dbPath, { pragmaTemplate });
+  const cache = createCache({ enabled: true });
+  const engine = createEngine({ db, cache });
+  const sweeper = createExpirationSweeper({
+    db,
+    clock: () => Date.now(),
+    sweepIntervalMs: 1000,
+    maxKeysPerSweep: 500,
+  });
+  sweeper.start();
+
+  const connections = new Set();
+  const server = createServer({ engine, port, connections });
+
+  if (gracefulShutdown) {
+    let shuttingDown = false;
+    function shutdown() {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      sweeper.stop();
+      for (const socket of connections) socket.destroy();
+      connections.clear();
+      server.close(() => {
+        db.close();
+        process.exit(0);
+      });
+    }
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+  }
+
+  server.listen(port, () => {
+    console.log(`RESPLite listening on port ${port}, db: ${dbPath}`);
+  });
+}
+
+const isCli = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (isCli) {
+  const noGraceful = process.argv.includes('--no-graceful-shutdown');
+  startServer({ gracefulShutdown: !noGraceful });
+}

package/src/migration/bulk.js

@@ -48,7 +48,7 @@ function sleep(ms) {
  * @param {number} [options.batch_keys=200]
  * @param {number} [options.batch_bytes=64*1024*1024] - 64MB
  * @param {number} [options.checkpoint_interval_sec=30]
- * @param {boolean} [options.resume=false]
+ * @param {boolean} [options.resume=true] - true: start from 0 or continue from checkpoint; false: always start from 0
  * @param {function(run): void} [options.onProgress] - called after checkpoint with run row
  */
 export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
@@ -60,7 +60,7 @@ export async function runBulkImport(redisClient, dbPath, runId, options = {}) {
     batch_keys = 200,
     batch_bytes = 64 * 1024 * 1024,
     checkpoint_interval_sec = 30,
-    resume = false,
+    resume = true,
     onProgress,
   } = options;
 

package/src/migration/index.js

@@ -113,11 +113,11 @@ export function createMigration({
 
     /**
      * Step 1 — Bulk import: SCAN all keys from Redis into the destination DB.
-     * Supports resume (checkpoint-based) and optional progress callback.
+     * Resume is on by default: first run starts from 0, later runs continue from checkpoint.
      *
-     * @param {{ resume?: boolean, onProgress?: (run: object) => void }} [opts]
+     * @param {{ resume?: boolean, onProgress?: (run: object) => void }} [opts] - resume (default true): start or continue automatically
      */
-    async bulk({ resume = false, onProgress } = {}) {
+    async bulk({ resume = true, onProgress } = {}) {
       const id = requireRunId();
       const client = await getClient();
       return runBulkImport(client, to, id, {

package/src/server/tcp-server.js

@@ -10,10 +10,15 @@ import { handleConnection } from './connection.js';
  * @param {object} options.engine
  * @param {number} [options.port=6379]
  * @param {string} [options.host='0.0.0.0']
+ * @param {Set<import('node:net').Socket>} [options.connections] If provided, each accepted socket is added here (for graceful shutdown).
  * @returns {import('node:net').Server}
  */
-export function createServer({ engine, port = 6379, host = '0.0.0.0' }) {
+export function createServer({ engine, port = 6379, host = '0.0.0.0', connections = null }) {
   const server = net.createServer((socket) => {
+    if (connections) {
+      connections.add(socket);
+      socket.once('close', () => connections.delete(socket));
+    }
     handleConnection(socket, engine);
   });
   return server;