name: wechat-db-access description: Read and query WeChat's local SQLite databases (EnMicroMsg.db) on Android with root. Covers SQLCipher decryption, message table schema, image/voice file path resolution, message content parsing, and building read-only tools on top of WeChat data. Load when building any WeChat data viewer, extractor, digest generator, or data pipeline. version: 1.0
category: android
WeChat DB Access Patterns
When to Use
- Building a WeChat message viewer, search tool, or data export
- Extracting messages from specific chats for analysis
- Resolving WeChat image/voice file paths for serving or processing
- Querying WeChat contact and chatroom data
- Any project that reads directly from WeChat's SQLite databases
DB Location & Key
WeChat's main message DB is EnMicroMsg.db under /data/data/com.tencent.mm/MicroMsg/<32-char-hash>/.
Find it:
su -c "find /data/data/com.tencent.mm/MicroMsg -name 'EnMicroMsg.db' -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -1"
SQLCipher key is usually a short hex string (e.g. e03ce81). On this device it's read from ~/pixelphone/event_bus/wechat_key or environment variable WECHAT_KEY, with a hardcoded fallback.
Querying via sqlcipher CLI
Always use su because WeChat's data directory is owned by the WeChat UID:
su -c 'sqlcipher /path/to/EnMicroMsg.db \
-cmd "PRAGMA key=<KEY>;" \
-cmd "PRAGMA cipher_compatibility=1;" \
-cmd "PRAGMA cipher_page_size=1024;" \
-cmd "PRAGMA query_only=true;" \
-cmd ".mode json" \
"SELECT ..."'
PITFALL: sqlcipher prints ok\n before the JSON output. Strip "ok" prefix before json.loads().
PITFALL: sqlcipher .mode json may pretty-print multi-line JSON arrays. Strip the ok\n prefix first, THEN parse the full output as JSON — don't parse line-by-line.
Key Tables
| Table | Key Columns | Notes |
|---|---|---|
message |
msgId, type, isSend, talker, content, createTime, imgPath | Main messages table |
rcontact |
username, nickname, conRemark, alias | Contacts + group names |
chatroom |
chatroomname, displayname, memberCount | Chatroom metadata |
Message Types
| type | Meaning | Content field | imgPath field |
|---|---|---|---|
| 1 | Text | Text or XML-wrapped text | — |
| 3 | Image | XML with CDN URLs | THUMBNAIL_DIRPATH://th_<hash> |
| 34 | Voice | XML with <voicemsg> |
Voice filename hash |
| 43 | Video | XML | — |
| 47 | Emoji/sticker | XML | — |
| 49 | Article/link/appmsg | XML with <url>, <title>, <des>, <thumburl> |
— |
High/unknown message types
WeChat uses very large type numbers (e.g. 822083633, 754974769) for internal structures:
- 822083633: Reply/reference with
<refermsg>block — references a prior message. Extract<title>and<displayname>from the XML. - 754974769: Special unsupported message ("当前微信版本不支持展示该内容").
For unknown types, try this fallback chain:
- Extract
<title>from XML → if found, use it as display text - If
<refermsg>present → parse reference info, show "[引用XX的消息] title" - If
<img>in content → show "[引用图片]" - If
<voicemsg>→ show "[引用语音]" - Otherwise strip XML tags. If result >200 chars, truncate to 150 (likely metadata garbage).
- If nothing useful — show "[未知消息 type=N]"
Article card fields (type 49)
For rich article display in web UIs, extract these from the XML:
<title>— article title<url>— article URL<des>— article description/summary<thumburl>— CDN thumbnail (binary protocol, not HTTP — use placeholder if needed)
HTML unescaping: WeChat XML content often contains   (space), &, etc. Use html.unescape() on extracted text fields.
Flask debug=False pitfall
When building WeChat web services with Flask in production mode (debug=False):
- Templates do NOT auto-reload on file changes
- Must restart the server manually after template edits
- Use
debug=Trueduring development, switch toFalsefor stable serving
Content Parsing
Chatroom messages have sender:\n prefix
yibooo:\nok 我来也整一个 快速看齐
Split on first \n when the first segment contains ::
if "\n" in content and ":" in content.split("\n")[0]:
display_text = content.split("\n", 1)[1]
XML content
Type 3/34/43/47/49 messages wrap data in <msg>...</msg> XML. For text display, strip all tags: re.sub(r"<[^>]+>", "", text).
For article links (type 49), extract <url> and <title> from the raw content.
Group Names
WeChat stores the custom group name in rcontact.nickname for @chatroom usernames. The chatroom.displayname field contains member nicknames, NOT the group name.
-- Correct: get group name from rcontact
SELECT COALESCE(NULLIF(r.nickname, ''), c.displayname, c.chatroomname) AS group_name
FROM chatroom c
LEFT JOIN rcontact r ON c.chatroomname = r.username
When the group has no custom name (rcontact.nickname is empty), fall back to chatroom.displayname (member names).
Image Path Resolution
WeChat's imgPath field stores paths like THUMBNAIL_DIRPATH://th_<32-char-hash>.
Actual file layout: image2/<first2>/<next2>/th_<hash> under the MicroMsg hash directory.
hash_part = img_path.replace("THUMBNAIL_DIRPATH://", "").replace("th_", "")
sub1, sub2 = hash_part[:2], hash_part[2:4]
real_path = f"{WECHAT_DATA_ROOT}/image2/{sub1}/{sub2}/th_{hash_part}"
For full images (not thumbnails), try the same path without th_ prefix.
Voice Path Resolution
Voice files have a complex directory structure that is NOT simply hash-prefix-based. The imgPath stores a bare hash (e.g. 05142107062628ef8e19f29104), while the actual file is at voice2/XX/YY/msg_<hash>.amr.
Use find to locate voice files — the subdirectory derivation is not straightforward:
# imgPath: "05142107062628ef8e19f29104"
# actual: voice2/66/33/msg_05142107062628ef8e19f29104.amr
su -c "find {WECHAT_DATA_ROOT}/voice2 -name '*{hash}*' | head -1"
Permission Handling
Termux runs as a different UID than WeChat. All file operations on WeChat's data dir require su:
- Check existence:
su -c "test -f <path> && echo yes" - Read/copy:
su -c "cp <src> <tmp> && chmod 644 <tmp>"— stage to /tmp, then read as Termux user Path.exists()will throwPermissionError— wrap with try/except and fall back tosuglob.glob()silently returns[](no exception) when the target dir is owned by another UID. This is the harder-to-diagnose failure mode: code likefor xml in glob.glob(f"{MM_BASE}/shared_prefs/*.xml")simply loops zero times, so downstream logic gets "no files found" rather than a permission error. Any Python code that scans WeChat's data dir withglobmust use asu -cfallback:
def _safe_glob(pattern: str) -> list[str]:
"""glob that falls back to su for dirs owned by another UID (e.g. WeChat shared_prefs)."""
import glob as _g
hits = _g.glob(pattern)
if hits:
return hits
# fallback: su -c ls (glob returns [] silently on PermissionError, unlike Path.exists)
r = subprocess.run(["su", "-c", f"ls -1 {pattern} 2>/dev/null"],
capture_output=True, text=True, timeout=5)
return [line.strip() for line in r.stdout.splitlines() if line.strip()] if r.returncode == 0 else []
Helpers:
def _safe_exists(path: str) -> bool:
try:
return Path(path).exists()
except PermissionError:
r = subprocess.run(["su", "-c", f"test -f {path} && echo yes || echo no"],
capture_output=True, text=True, timeout=5)
return "yes" in r.stdout
def _su_read_text(path: str) -> str:
"""Read a file owned by another UID via su (e.g. WeChat shared_prefs XML)."""
r = subprocess.run(["su", "-c", f"cat {path}"], capture_output=True, text=True, timeout=5)
return r.stdout if r.returncode == 0 else ""
def _su_copy(src: str, dst: str, chown_uid: int = None, chown_gid: int = None) -> bool:
"""Copy a file owned by another UID via su. After su cp, the copy is root-owned;
os.chown() will fail silently (PermissionError swallowed by except-pass).
Must use su -c chown to fix ownership so non-root processes can read the copy."""
r = subprocess.run(["su", "-c", f"cp {src} {dst}"], capture_output=True, timeout=60)
if r.returncode != 0:
return False
if chown_uid is not None:
subprocess.run(["su", "-c", f"chown {chown_uid}:{chown_gid} {dst}"],
capture_output=True, timeout=10)
return True
def _safe_chown(path: str, uid: int, gid: int) -> bool:
"""chown that falls back to su when os.chown fails (non-root Termux)."""
try:
os.chown(path, uid, gid)
return True
except (OSError, PermissionError):
r = subprocess.run(["su", "-c", f"chown {uid}:{gid} {path}"],
capture_output=True, timeout=10)
return r.returncode == 0
PITFALL: os.chown() fails silently on non-root Termux — after su -c cp, the copied file is owned by root. os.chown() raises PermissionError which gets swallowed by except OSError: pass, leaving the file root-owned and unreadable by the Termux process. Always use _safe_chown() (or su -c chown directly) after any su -c cp operation.
Multi-Account Key Storage
When multiple WeChat users share a device, each has its own EnMicroMsg.db under a different hash directory. Keys differ per account (MD5(IMEI + UIN)[:7]).
Per-account key file pattern (used by WeChat Viewer):
~/wechat-viewer/.wechat_key_<32-char-dir-hash>
Example:
echo "e03ce81" > ~/wechat-viewer/.wechat_key_653cdc2320abb089e149a3f7a7683fcf
echo "<other_key>" > ~/wechat-viewer/.wechat_key_ec4f423b316d41e9af5e8398155cf105
Per-account display name:
echo "小伙子" > ~/wechat-viewer/.wechat_name_653cdc2320abb089e149a3f7a7683fcf
echo "火星人" > ~/wechat-viewer/.wechat_name_ec4f423b316d41e9af5e8398155cf105
Discovery: su -c "ls -d /data/data/com.tencent.mm/MicroMsg/*/" finds all account dirs. Test each DB with key: su -c "sqlcipher path -cmd 'PRAGMA key=...;' 'SELECT sqlite_version();'". If "file is not a database" → wrong key.
Frida key extraction: Hook net.sqlcipher.database.SQLiteDatabase.openDatabase() to capture password. BUT Android 16 + Frida 17.x has attach timeout issues. Key files are more reliable. Only use Frida as last resort and with WeChat process actively running.
When building Flask/Django services that serve WeChat media:
- Stage files to
/tmpviasu cp— Flask can't read root-owned files - Cache staged files (check
/tmpbefore re-copying) - Voice files need ffmpeg transcoding to MP3 for browser playback (AMR/SILK not browser-compatible)
Communication skills
These complement db-access (load as needed):
wechat-voice-sender— TTS → voice message deliverywechat-image-sender— image delivery via internal hookwechat-group-digest— digest generation patterns
Reference Files
references/task-verification.md— 验证助手在微信里回复「已处理」的任务是否真正完成,还是卡住/失败references/device-config.md— Current device DB path, key, chatroom IDsreferences/viewer-template.md— Flask project template location