sql-md-sync

library0.1.2jsnpmunverified

Bidirectional SQLite to Markdown sync CLI for git-diffable database history. Current stable version is 0.1.2, released on npm with a MIT license and Node >=20 requirement. It projects each SQLite row as a Markdown file with YAML frontmatter, enabling row-level diffs, PR reviews, and merge workflows on database content without sacrificing the ability to run real SQL queries after materializing back to SQLite. Differentiates from alternatives like Dolt (proprietary format) and sqlite3 .dump (textual but not per-row granular) by providing a human-editable, diff-friendly Markdown tree that fully round-trips to SQLite, with schema stored as SQL files and BLOBs handled via sidecar files.

database devops

npm install sql-md-sync

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQL-MD-SYNC

sql-md-sync

databasejavascriptv0.1.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'sql-md-sync'

✗ const run = require('sql-md-sync')

ESM-only since v0.1.0; TypeScript types included.

exportSync

✓ import { exportSync } from 'sql-md-sync/export'

✗ import { exportSync } from 'sql-md-sync'

Subpath exports for export, import, init, validate, commit require explicit path.

importSync

✓ import { importSync } from 'sql-md-sync/import'

Import the named function; no default export.

Shows programmatic usage of sql-md-sync: init, export, import, and validate with round-trip check.

import { run } from 'sql-md-sync'; import { exportSync } from 'sql-md-sync/export'; import { importSync } from 'sql-md-sync/import'; import { validate } from 'sql-md-sync/validate'; // Initialize a new project (creates .sqlmdsync.json) run(['init']); // Export SQLite database to Markdown const exportResult = exportSync({ db: './mydata.db', out: './repo' }); console.log(`Exported ${exportResult.tables.length} tables`); // Import Markdown back to SQLite const importResult = importSync({ md: './repo', out: './mydata.db' }); console.log(`Imported ${importResult.rowCount} rows`); // Validate round-trip integrity const validation = validate('./repo', { roundTrip: true }); console.log(`Valid: ${validation.valid}, errors: ${validation.errors.length}`);

Debug

Known issues

gotchaNode version must be >=20

fix

Upgrade Node.js to v20 or later.

affects: >=0.1.0

gotchaESM only; does not support require().

fix

Use import syntax or dynamic import.

affects: >=0.1.0

gotchaMarkdown files must not have leading/trailing whitespace in frontmatter; YAML strict mode enforced.

fix

Ensure frontmatter is valid YAML without extra spaces.

affects: >=0.1.0

deprecatedThe `--stage` flag in commit command is deprecated; use `--print` instead.

fix

Use `sql-md-sync commit --print` instead of `--stage`.

affects: >=0.1.2

breakingIn version 0.1.1 the export subpath changed from 'sql-md-sync' to 'sql-md-sync/export'.

fix

Update import paths: import { exportSync } from 'sql-md-sync/export'.

affects: >=0.1.1

Errors

Common errors & fixes

Error: Cannot find module 'sql-md-sync/export'

Import path changed from default export to subpath export.

fix

Change import to: import { exportSync } from 'sql-md-sync/export';

TypeError: (0 , sql_md_sync.importSync) is not a function

Using incorrect import path for importSync.

fix

Use: import { importSync } from 'sql-md-sync/import';

YAMLException: bad indentation of a mapping entry

Frontmatter YAML has incorrect indentation.

fix

Check frontmatter indentation; ensure keys and values are properly aligned.

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite driver for database operations

yamlrequiredYAML frontmatter parsing and serialization

Agent activity

24 hits · last 30 days

node