SQLite on Dev TLDRLSS

Don't Be Fooled by SQLite's Casualness! What Are the Dynamic Type Pitfalls? Why Is ALTER TABLE Half-Baked? How to Build a Defensive Programming Architecture in Node.js for Painless Schema Upgrades?

Tue, 19 May 2026 18:10:00 +0800

Imagine a recycling bin where you clearly put a label saying “Plastic Bottles Only”, but when someone drops a piece of paper in, it silently accepts it without a single word of protest?

This is the spine-chilling experience when developers meet the SQLite type system for the first time.

If you are used to the strict customs officer style of PostgreSQL (where incorrect types are directly denied entry), SQLite’s casualness might make you question your life.

Even more terrifyingly, when you want to modify a table structure, it will tell you:

“The table cannot be modified directly. Please build a new house, move the furniture over, and then blow up the old house.”

SQLite Under the Hood Has Only 5 Storage Classes

No matter what fancy type names you declare in CREATE TABLE (VARCHAR(255), BIGINT, DECIMAL), SQLite under the hood only recognizes these 5 storage classes:

Storage Class	Description
NULL	Null value
INTEGER	Integer (automatically occupies 1 to 8 bytes depending on the magnitude)
REAL	Floating-point number (fixed 8 bytes)
TEXT	String (default UTF-8 encoding)
BLOB	Binary large object (stored exactly as entered)

The types you set on columns are merely “suggestions” to SQLite, not “mandatory rules”.

This is called “Type Affinity”. SQLite will try to convert your data into the suggested type, but if it cannot, it will just stuff the original data in anyway without throwing any errors.

You can declare an age INTEGER column in SQLite and then insert the string 'forever eighteen'; it will accept it with pleasure.

Three Easiest Type Pitfalls to Step Into

Pitfall 1: No Native Boolean

SQLite has no boolean type. True and False can only be represented by the integers 1 and 0.

When you fetch data from SQLite using Node.js, you will get the number 1 or 0, not true or false.

If you directly perform a check like if (user.is_admin === true), it will never be true.

Pitfall 2: No Date/Time Type

SQLite has no date/time type. You can only store time as:

Storage Method	Example	Pros & Cons
TEXT (ISO-8601 string)	`'2026-05-19T18:00:00Z'`	Most recommended, high readability, seamless conversion when moving to PostgreSQL in the future
INTEGER (Unix Timestamp)	`1747656000`	Small footprint, but not human-readable

Never store dates in arbitrary custom formats like 2026/5/19 6:00 PM, otherwise data migration in the future will be a disaster.

Pitfall 3: Inserting a String into an Integer Column Won’t Throw an Error

In PostgreSQL, inserting a string into an INTEGER column throws an error immediately. But SQLite will only try to convert it silently, and if it fails, it accepts it as-is.

This means dirty data might quietly sneak into your database until one day your program crashes due to receiving an unexpected type, only then will you discover the issue.

Defensive Programming: Treating a Casual Database with a Strict Attitude

Faced with SQLite’s casualness, you must build strict defense mechanisms in Node.js development:

Defense Level	Tool	Role
Compile-time Guard	TypeScript	Catch incorrect types at the code-writing stage
API Entry Validation	Zod	Validate incoming data strictly (ensure age is always a number)
Under-the-hood Type Cast	Prisma / Drizzle ORM	Automatically handle type differences between SQLite and PostgreSQL

Moving the “gatekeeper of data validation” from the database layer to the Node.js application layer is a key strategy to leverage SQLite’s development speed while ensuring future scalability.

When using an ORM, as long as you declare type: 'boolean' in your code, the ORM automatically converts it to 1/0 when saving to SQLite, and converts it back to true/false when reading, perfectly masking the underlying type differences.

ALTER TABLE is Half-Baked: What Can and Cannot Be Modified

SQLite’s support for modifying table structures is very limited:

Operation	Supported
Add Column (`ADD COLUMN`)	Yes
Rename Column (`RENAME COLUMN`)	Yes
Drop Column (`DROP COLUMN`)	Yes (in newer versions)
Rename Table (`RENAME TO`)	Yes
Change Column Type	No
Add/Remove `UNIQUE`, `NOT NULL` Constraints	No
Modify Primary Key	No
Modify Foreign Key	No

Once you need to make any of the “unsupported” modifications, SQLite requires you to execute the “recreate and move” strategy.

The Four-Step Recreate & Move: SQLite’s Table Upgrade Way

Since it cannot be modified directly, the standard practice recommended by the official docs is building a new house, moving the furniture, blowing up the old house, and posting the new doorplate:

Step	Action	Description
1	Create New Table	`CREATE TABLE users_new (...)` using the correct structure
2	Copy Data	`INSERT INTO users_new SELECT ... FROM users`
3	Drop Old Table	`DROP TABLE users`
4	Rename Table	`ALTER TABLE users_new RENAME TO users`

These four steps must be executed in one breath; any power outage or application crash midway will result in data loss.

Ensuring Upgrades Don’t Lose Data: Two Safety Lines of Defense

Defense Line 1: Physical Defense, Copy the File Directly

SQLite is essentially just a file. Before executing any schema changes, simply make a copy of the .db file as a backup.

const fs = require('fs');
fs.copyFileSync('my_project.db', 'my_project_backup.db');

If things go wrong, replacing the file restores everything in an instant. This is an advantage that other large databases cannot offer.

Defense Line 2: Transaction Wrapper, The Database Time Machine

Wrap all migration steps inside a single Transaction; if any step fails, the entire process will automatically roll back as if nothing ever happened.

const Database = require('better-sqlite3');
const db = new Database('my_project.db');

const migrateData = db.transaction(() => {
  db.prepare(`
    CREATE TABLE users_new (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      age INTEGER NOT NULL DEFAULT 18
    )
  `).run();

  db.prepare(`
    INSERT INTO users_new (id, name, age)
    SELECT id, name, COALESCE(age, 18) FROM users
  `).run();

  db.prepare('DROP TABLE users').run();
  db.prepare('ALTER TABLE users_new RENAME TO users').run();
});

try {
  migrateData();
  console.log('Table upgraded successfully');
} catch (error) {
  console.error('Upgrade failed, data safely restored:', error.message);
}

“Backup file + Transaction binding” is the airbag of your database migration.

Control the Casual SQLite with a Strict Attitude

Harness the casual SQLite with a strict application-layer architecture to enjoy its lightning-fast development speed while avoiding future technical debt.

SQLite’s type system is highly casual, and ALTER TABLE has many limitations.

However, as long as you perform TypeScript type checking + Zod validation + ORM abstraction on the Node.js side, paired with the safety strategy of physical backup + Transaction, you can safely enjoy the development efficiency brought by SQLite while paving the way to migrate to PostgreSQL in the future.

Reference

Stop Using PostgreSQL for Everything! What Are SQLite's Embedded Architecture and Zero-Config Advantages? Where Are SQLite's Limits? When Should You Choose SQLite, and When PostgreSQL?

Tue, 19 May 2026 18:00:00 +0800

Have you ever thought about the fact that the browser you open every day, the communication software on your phone, and even the note-taking tool on your desktop all hide the same lightweight database?

It does not require you to install any server software, requires no account or password settings, and does not even need an internet connection. It is simply a file, quietly lying on your hard drive, ready to serve you at any time.

This low-key existence is SQLite.

What is SQLite? The World’s Most Widely Deployed Database

SQLite is an embedded relational database engine written in C.

It has no independent server process, but is directly embedded into your application to run.

This is completely different from PostgreSQL or MySQL that you are familiar with. Traditional databases are independent servers running separately, and your program must “communicate” with them via a network protocol (TCP/IP).

But SQLite is different; it is simply a block of code, running directly inside your application, reading and writing that .db file on your hard drive.

Comparison Dimension	SQLite (Embedded)	PostgreSQL (Client-Server)
Operating Mode	Directly embedded in application, no independent server	Independent server process, via network connection
Configuration	Zero config, no installation, no credentials	Requires installation, setting account/password & firewall
Data Storage	Single cross-platform file	Multiple files under the server directory
Backup Method	Directly copy that file	Requires dedicated tools like pg_dump

It is precisely because of this “plug-and-play” characteristic that SQLite has become the world’s most widely deployed database engine.

From Android and iOS operating systems, Chrome and Firefox browsers, to Adobe Lightroom, WhatsApp, and even the flight system of the Airbus A350, it is everywhere.

Using SQLite in Node.js

If you are a Node.js developer, using SQLite is extremely simple. You do not need to install any database server software on your computer, you only need to install an npm package to get started.

The most commonly used choices in the industry today:

Package Name	Characteristics	Recommended Scenario
`sqlite3`	Most established, supports asynchronous APIs	When needing to handle many asynchronous tasks concurrently
`better-sqlite3`	Excellent performance, intuitive API design, extremely fast	Top recommendation, for development efficiency and execution speed

Creating a database and querying it with better-sqlite3 takes less than five minutes:

const Database = require('better-sqlite3');
const db = new Database('my_project.db');

db.prepare('CREATE TABLE IF NOT EXISTS users (name TEXT, age INTEGER)').run();

const insert = db.prepare('INSERT INTO users (name, age) VALUES (?, ?)');
insert.run('John', 25);

const user = db.prepare('SELECT * FROM users WHERE name = ?').get('John');
console.log(user); // { name: 'John', age: 25 }

If the file does not exist, better-sqlite3 will automatically create it for you.

SQLite Supports SQL Syntax More Powerful Than You Think

Many people think SQLite is very basic, but it supports the vast majority of standard SQL syntax, including many advanced features:

Syntax Category	Supported Items
Basic Operations	`SELECT`, `INSERT`, `UPDATE`, `DELETE`
Data Definition	`CREATE TABLE`, `CREATE INDEX`, `CREATE VIEW`
Advanced Querying	`WITH` (Recursive CTEs), Window Functions
Conflict Handling	`UPSERT` (`INSERT ... ON CONFLICT DO UPDATE`)
JSON Processing	Built-in functions like `json_extract`, `json_array`, `json_object`, etc.
Transaction Control	`BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`
Join Queries	`INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, and `FULL OUTER JOIN`

SQLite’s core philosophy is “small and beautiful”, supporting most SQL capabilities you need daily while remaining extremely lightweight.

Where Are SQLite’s Limits?

Lightness comes at a price. If SQLite is compared to a hipster grocery store with only one checkout counter, then PostgreSQL is a Costco equipped with 50 cash registers.

1. Write Traffic Jam

When SQLite writes data, it locks the entire database file.

Imagine a restaurant with only one restroom: 100 people can look at the menu outside (read) at the same time, but as long as 1 person goes in and locks the door (write), everyone else can only queue up and wait.

Although enabling WAL mode (Write-Ahead Logging) can improve concurrent read/write performance, fundamentally it still cannot achieve multi-threaded concurrent writes to different data rows.

2. Cannot Span Multiple Servers

The essence of SQLite is a physical file. If your system is deployed across multiple servers (horizontal scaling), these servers cannot safely share the same file.

3. Lack of Fine-Grained Permission Management

SQLite has no concept of “user accounts.” Anyone who can read that .db file at the operating system level can see and modify all the data.

For business systems that require strict personal data audits, this is unacceptable.

SQLite vs. PostgreSQL: Technology Selection Decisions

Tools are neither good nor bad, only suitable or not. Here is an ultimate checklist to help you make decisions:

Question	Answer “Yes” → Choose SQLite	Answer “No” → Choose PostgreSQL
Is there only one backend server, or does it run entirely locally?	Yes	No (requires horizontal scaling, multiple machines)
Is the system behavior heavily read-dominated, without high-frequency concurrent writes?	Yes	No (users will compete to write concurrently)
No need for fine-grained database account permissions or advanced indexing?	Yes	No (heavily dependent on advanced features)

More specific scenario comparisons:

Scenario	Recommended Choice	Reason
Desktop Software, Mobile Apps, IoT Devices	SQLite	Data travels with the device, no installation
Personal Blogs, Showcase Websites	SQLite	Read-heavy, write-light, saves server maintenance costs
Rapid Prototyping, Demos	SQLite	Just create a file to get started
Community Forums, E-commerce Platforms	PostgreSQL	High concurrency writes, requires row-level locking
Distributed Deployment on Multiple Servers	PostgreSQL	Needs to share data source across machines
Sensitive Systems like Medical, Financial	PostgreSQL	Requires strict role-based permission control

Is Your Database a Pocket Note or a Central Switchboard?

If the data is “single-machine, static, single-owner”, choose SQLite to enjoy extreme lightweight and freedom;

If the data is “cloud, dynamic, highly interactive”, let PostgreSQL take over.

SQLite’s core philosophy is “an internal component of the application”, whereas PostgreSQL is positioned as “an independent center of the system architecture”.

Next time you make an architectural decision, don’t rush to bring out PostgreSQL. Ask yourself first:

“Is my database a pocket note, or a central switchboard?”

Once the answer is clear, the choice naturally becomes obvious.