Skip to content

Conversation

@dmytech462
Copy link

Summary

This PR adds SQLCipher encryption support to WatermelonDB, enabling encrypted SQLite databases on iOS and Android.

Based on Nozbe#1635, merged and refined for our needs.

Key changes:

  • New passphrase option in SQLiteAdapter to enable database encryption
  • Bundled SQLCipher amalgamation (sqlite3.c/h) for native encryption support
  • Automatic plaintext database detection and wipe - when encryption is enabled (passphrase provided) and an existing unencrypted database is detected via isPlaintextSqlite(), the database files are automatically wiped and recreated as encrypted. This prevents encryption errors when switching from plaintext to encrypted mode.
  • Optimized plaintext detection - reads only the first 16 bytes of the file to check for SQLite header signature, avoiding full database open
  • Fork configuration - updated package name to @pinginc/watermelondb and URLs to pinginc repository for npm publishing

Usage

  const adapter = new SQLiteAdapter({
    schema,
    passphrase: 'your-encryption-key', // enables SQLCipher encryption
  })

Note

When passphrase is provided and the existing database is unencrypted (plaintext), the database will be automatically wiped (deleted and recreated). This happens because SQLCipher cannot open a plaintext database with encryption enabled. Added to avoid crash errors. Ensure you handle data migration or backup before enabling encryption on an existing unencrypted database.

Checklist

  • I have updated the summary to explain what's changed.
  • I have added unit and integration tests to cover the new functionality.
  • I have followed the PR Guidelines.

Based on PR Nozbe#1635 from Nozbe/WatermelonDB:
- Add SQLCipher amalgamation files
- Update native C++ to accept password parameter
- Add iOS SQLCipher support via podspec ($isEncryptedDB flag)
- Add Android SQLCipher support via build.gradle and CMakeLists.txt
- Add passphrase option to SQLiteAdapterOptions
Removed redundant fileExists() function and combined file existence
check into isPlaintextSqlite() to avoid opening the file twice during
database initialization.
@dmytech462 dmytech462 self-assigned this Jan 14, 2026
@jinsoo601 jinsoo601 merged commit 77a490b into master Jan 15, 2026
1 check passed
@jinsoo601 jinsoo601 deleted the ENT-1060-sqlcipher-encryption branch January 15, 2026 00:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants