docs: proper badge links, clean comparison matrix and formatting

Author: Pushkar

README.md

@@ -1,6 +1,25 @@
 # sqlite2pg
 
-A zero-config CLI and Node.js library to convert SQLite databases into clean, PostgreSQL-compatible SQL migrations for Supabase, Neon, and standard PostgreSQL instances.
+<div align="center">
+
+**Zero-config SQLite to PostgreSQL & Supabase Exporter and Migrator.**
+
+[![CI](https://github.com/pushkarreddyy/sqlite2pg/actions/workflows/ci.yml/badge.svg)](https://github.com/pushkarreddyy/sqlite2pg/actions)
+[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-339933.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Migrates local SQLite, LibSQL, and Turso databases directly to Supabase, Neon, AWS RDS, or standard PostgreSQL instances with strict types, transaction wrapping, and sequence synchronization.
+
+```
+ ┌─────────────────┐       sqlite2pg       ┌──────────────────────────────┐
+ │  Local SQLite   │ ────────────────────► │  PostgreSQL / Supabase       │
+ │  (app.db)       │      Fast DDL & Data  │  (Strict Types, RLS, setval) │
+ └─────────────────┘                       └──────────────────────────────┘
+```
+
+</div>
 
 ---
 
@@ -12,7 +31,7 @@ A zero-config CLI and Node.js library to convert SQLite databases into clean, Po
 npx sqlite2pg ./app.db -o migration.sql
 ```
 
-For Supabase targets (enables Row Level Security and UUID extensions):
+For Supabase targets (automatically configures Row Level Security and UUID extensions):
 
 ```bash
 npx sqlite2pg ./app.db -o migration.sql --target supabase
@@ -36,24 +55,27 @@ npx sqlite2pg ./app.db --conn "postgres://postgres:password@db.supabase.co:5432/
 
 ---
 
-## Why sqlite2pg?
+## Comparison
 
-Dumping SQLite with standard `sqlite3 .dump` or migrating via `pgloader` creates common failure points on PostgreSQL:
-
-- **AUTOINCREMENT Syntax**: SQLite's `INTEGER PRIMARY KEY AUTOINCREMENT` is invalid in PostgreSQL. `sqlite2pg` maps this to `BIGSERIAL PRIMARY KEY` or standard `GENERATED BY DEFAULT AS IDENTITY`.
-- **Foreign Key Load Order**: Standard SQL dumps insert rows in table order, failing when child tables appear before parents. `sqlite2pg` creates tables, loads all data in transactions, and adds foreign key constraints at the end.
-- **Sequence Desync**: Inserting explicit primary keys into PostgreSQL leaves serial sequences out of sync, causing subsequent `INSERT` statements from your application to throw duplicate key errors. `sqlite2pg` automatically includes `SELECT setval(...)` resets for all sequences.
-- **Boolean Normalization**: SQLite represents booleans as integers (`0`/`1`) or strings (`'0'`/`'1'`). `sqlite2pg` casts them to strict PostgreSQL `TRUE`/`FALSE` literals.
-- **Timestamp Parsing**: SQLite `strftime` formats (`YYYY-MM-DD HH:MM:SS`), ISO strings, and unix epochs are converted to valid PostgreSQL `TIMESTAMPTZ` values.
-- **Bytea and Hex Blobs**: Binary BLOB fields are encoded into PostgreSQL `'\x...'::bytea` hex format.
-- **Reserved Words**: Table and column identifiers matching SQL keywords (`user`, `order`, `group`, `table`) are properly quoted.
-- **Zero Native Toolchain**: Built on Node's native SQLite engine with no Python, C++, or Common Lisp dependencies. Runs directly via `npx` across macOS, Linux, and Windows.
+| Feature / Issue | Standard `sqlite3 .dump` | `pgloader` | `sqlite2pg` |
+| :--- | :---: | :---: | :---: |
+| **`AUTOINCREMENT` Syntax** | Fails in Postgres | Requires custom config | **Maps to `BIGSERIAL` / `IDENTITY`** |
+| **Foreign Key Load Order** | Fails on insert order | Complex setup | **Defers constraints after data load** |
+| **Sequence Synchronization** | Fails on next app insert | Inconsistent | **Auto-generates `setval` for all tables** |
+| **Boolean Values (`0`/`1`)** | Type mismatch error | Partial | **Normalizes to strict `TRUE`/`FALSE`** |
+| **Timestamp & Epoch Parsing** | Format errors | Inconsistent | **Normalizes to valid `TIMESTAMPTZ`** |
+| **Binary BLOBs** | Fails on `X'...'` syntax | Memory heavy | **Encodes as `'\x...'::bytea`** |
+| **Reserved SQL Keywords** | Fails on `user`, `order`, etc. | Needs mapping rules | **ANSI double-quotes all identifiers** |
+| **Supabase RLS & Extensions** | Not supported | Not supported | **Built-in with `--target supabase`** |
+| **Runtime & Dependencies** | Shell-dependent | Common Lisp / sbcl | **Zero-dependency Node.js native engine** |
 
 ---
 
 ## Type Conversions
 
-| SQLite Type / Affinity | PostgreSQL Type | Handling Notes |
+`sqlite2pg` inspects SQLite table declarations and sampled data to construct strict PostgreSQL schemas:
+
+| SQLite Declaration | PostgreSQL Type | Handling Notes |
 | :--- | :--- | :--- |
 | `INTEGER PRIMARY KEY` (rowid) | `BIGSERIAL PRIMARY KEY` | Uses `BIGINT GENERATED ... AS IDENTITY` when `--identity` is set |
 | `INTEGER`, `INT`, `INT4` | `INTEGER` | Standard 32-bit integer |
@@ -100,9 +122,9 @@ Options:
 
 ---
 
-## Programmatic Usage
+## Programmatic API
 
-You can use `sqlite2pg` directly inside your Node.js or TypeScript application:
+`sqlite2pg` can be used directly in TypeScript or Node.js scripts:
 
 ```typescript
 import { convert, introspect } from 'sqlite2pg';
@@ -118,12 +140,12 @@ const { sql, stats } = convert('./app.db', {
   batchSize: 1000,
 });
 
-console.log(`Generated migration in ${stats.durationMs}ms`);
+console.log(`Exported ${stats.tableCount} tables and ${stats.rowCount} rows in ${stats.durationMs}ms`);
 ```
 
 ---
 
-## Common Use Cases
+## Common Recipes
 
 ### Inspect schema without exporting
 
@@ -143,7 +165,7 @@ npx sqlite2pg ./app.db --include users,orders,products -o subset.sql
 npx sqlite2pg ./app.db --schema-only -o schema.sql
 ```
 
-### SQL standard identity columns
+### Use SQL-standard identity columns
 
 ```bash
 npx sqlite2pg ./app.db --identity -o migration.sql
@@ -164,7 +186,7 @@ npm install
 # Build TypeScript
 npm run build
 
-# Run unit and integration tests
+# Run test suite
 npm test
 ```
 

package.json

@@ -11,7 +11,7 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "node --import tsx/esm tests/converter.test.ts",
+    "test": "tsx --test tests/*.test.ts",
     "start": "tsx src/cli.ts"
   },
   "keywords": [