@irithell-js/better-sqlite3-termux

Wrapper for the better-sqlite3 module, specifically designed to resolve compilation and execution failures of native C++ dependencies on Termux (Android). The package acts as a Drop-in Replacement, providing full compatibility with existing code and supporting both CommonJS and ESM.

Architecture and Solution

Android-based systems use emulated partitions (FUSE/FAT) on /sdcard/ that do not have native support for creating symbolic links (symlinks) or strict execution permissions. Since the generic better-sqlite3 module depends on node-gyp to compile C++ code and the base SQLite itself, the traditional installation fails on the phone's internal storage.

The @irithell-js/better-sqlite3-termux resolves this bottleneck through an isolation architecture:

1. Analytical Detection: Reads environment variables (process.env.PREFIX) to identify if the current runtime is Termux or a standard Linux server.
2. System Dependency Injection: Triggers the system package manager (pkg) to install required repositories and C libraries (build-essential, clang, python, sqlite, etc).
3. Hash Isolation: Calculates a unique MD5 identifier based on your project directory to create an aseptic build environment.
4. Background Compilation: Runs the native rebuild of the SQLite engine and injects the correct paths via a .json state file.
5. Original Types: The module provides oroginal types from better-sqlite3.

Installation

npm install @irithell-js/better-sqlite3-termux

IMPORTANT

If your environment blocks the post-installation script for some reason, run this command explicitly.

node ./node_modules/@irithell-js/better-sqlite3-termux/dist/install.cjs

# or

node ./node_modules/@irithell-js/better-sqlite3-termux/dist/install.mjs

How to Use

Usage is identical to the original package. No refactoring is required in your current code; simply replace the import or require source.

CommonJS

const Database = require("@irithell-js/better-sqlite3-termux");

const db = new Database("bot.db");
db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");

const insert = db.prepare("INSERT INTO users (name) VALUES (?)");
insert.run("Irithell");

const row = db.prepare("SELECT * FROM users").get();
console.log(row.name);

ESM

import Database from "@irithell-js/better-sqlite3-termux";

const db = new Database("bot.db");
// Normal database operations...

Version Control (Update & Downgrade)

By default, the proxy automatically fetches and compiles the latest version of the original better-sqlite3 package. If you need to pin a specific version, downgrade, or update, you can do so seamlessly without cluttering your project with broken binaries.

There are two methods to specify the target version:

Method 1: Via package.json (Recommended)

You can define the desired version using a custom irithell block in your project's root package.json. Note: Upon the first successful installation, the proxy features an Auto-Scaffolding mechanic that will automatically inject this block with the currently compiled version for your convenience.

{
  "name": "your-project",
  "dependencies": {
    "@irithell-js/better-sqlite3-termux": "^1.0.0"
  },
  "irithell": {
    "sqliteVersion": "12.9.0"
  }
}

Method 2: Via Environment Variable

You can also force a specific version directly from the terminal during installation:

SQLITE_VERSION=12.9.0 npm install @irithell-js/better-sqlite3-termux

Forcing the Engine Rebuild

If you change the version in your package.json after the initial installation, simply trigger the installer directly to safely destroy and rebuild the isolated engine:

node ./node_modules/@irithell-js/better-sqlite3-termux/dist/install.cjs

Internal Technical Features

Silent Failure Prevention

When package managers set the ignore-scripts = true restriction by default, compilation in the postinstall lifecycle is blocked without emitting logs. This module features a handler that detects if the silent compilation failed during your application's initialization and prevents a generic Node crash with instructions via logs.

Environment Migration (Cross-Environment Auto-Recovery)

When developing on Termux and later moving the entire project folder to a Linux VPS or Docker container, binary architectures conflict. The proxy registers metadata containing the source architecture at the time of installation. During the first execution on the new platform, the module intercepts the discrepancy in the binary, destroys the original engine, and automatically initiates a native rebuild focused on the new kernel.

Cleanup

If it is necessary to delete the compiled instances in Termux memory, the isolation directory is located at:

~/.sqlite3_engines/