> For the complete documentation index, see [llms.txt](https://docs.sourcedev.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sourcedev.pro/src-phone/database.md).

# Database

The complete schema is distributed as `install.sql`. Import that file instead of creating tables manually from this page.

## Upgrade procedure

1. Stop `src-phone`.
2. Back up all `src_phone_%` tables.
3. Import the new `install.sql`.
4. Review SQL errors before starting the resource.
5. Start `src-phone` and test an existing character.

The schema contains additive `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` statements. Do not remove migration statements because a new database appears to work without them; existing installations may still require them.

## Table groups

| Feature                       | Tables                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Core identity and preferences | `src_phone_data`, `src_phone_kv`                                                                                                                                                                                                                                                                                                           |
| Contacts and messages         | `src_phone_contacts`, `src_phone_messages`, `src_phone_pins`, `src_phone_message_settings`                                                                                                                                                                                                                                                 |
| Mail and media                | `src_phone_mails`, `src_phone_photos`, `src_phone_voice_memos`                                                                                                                                                                                                                                                                             |
| Music                         | `src_phone_playlists`, `src_phone_playlist_tracks`                                                                                                                                                                                                                                                                                         |
| Z                             | `src_phone_z_users`, `src_phone_z_posts`, `src_phone_z_likes`, `src_phone_z_reposts`, `src_phone_z_comments`, `src_phone_z_comment_likes`, `src_phone_z_follows`                                                                                                                                                                           |
| News and listings             | `src_phone_news`, `src_phone_yellowpages`                                                                                                                                                                                                                                                                                                  |
| Bank history                  | `src_phone_bank_transactions`                                                                                                                                                                                                                                                                                                              |
| MyFans                        | `src_phone_myfans_accounts`, `src_phone_myfans_posts`, `src_phone_myfans_likes`, `src_phone_myfans_comments`, `src_phone_myfans_follows`, `src_phone_myfans_subscriptions`, `src_phone_myfans_purchases`, `src_phone_myfans_wallet_transactions`, `src_phone_myfans_blocks`, `src_phone_myfans_messages`, `src_phone_myfans_notifications` |
| Vibe                          | `src_phone_vibe_profiles`, `src_phone_vibe_swipes`, `src_phone_vibe_matches`, `src_phone_vibe_messages`                                                                                                                                                                                                                                    |
| MyCloud                       | `src_phone_cloud_accounts`, `src_phone_cloud_links`, `src_phone_cloud_kv`, `src_phone_cloud_migrations`                                                                                                                                                                                                                                    |
| Crypto wallet                 | `src_phone_crypto_wallets`, `src_phone_crypto_balances`, `src_phone_crypto_transactions`                                                                                                                                                                                                                                                   |
| Wi-Fi                         | `src_phone_routers`, `src_phone_router_connections`                                                                                                                                                                                                                                                                                        |
| Cellular                      | `src_phone_cellular_accounts`, `src_phone_cellular_purchases`, `src_phone_cellular_usage`                                                                                                                                                                                                                                                  |

## Data ownership

Phone data uses two scopes:

* Character scope uses the framework identifier, normally `citizenid`.
* MyCloud scope uses `account_id` and follows the authenticated cloud account.

Do not replace one scope with the other in custom queries. Character contacts, phone numbers, and some feature records must not leak between characters; cloud preferences and wallet state must remain account-scoped.

## Collation and identifier length

The bundled schema uses `utf8mb4` and Unicode-compatible collation for user-facing text. Preserve this when migrating tables or indexes. Framework identifiers are generally stored in `VARCHAR(50)` or `VARCHAR(64)` columns depending on the feature.

Before changing identifier width, inspect every table and related index. Truncating an identifier can merge data from different characters.

## Verification queries

Confirm the core tables exist:

```sql
SHOW TABLES LIKE 'src_phone_%';
```

Check whether phone identities are being created:

```sql
SELECT citizenid, phone_number, mail_address
FROM src_phone_data
ORDER BY citizenid
LIMIT 20;
```

Check the latest messages:

```sql
SELECT id, sender, receiver, time, is_read
FROM src_phone_messages
ORDER BY id DESC
LIMIT 20;
```

Check account links without exposing password hashes:

```sql
SELECT citizenid, account_id, auto_login, last_used_at
FROM src_phone_cloud_links
ORDER BY last_used_at DESC
LIMIT 20;
```

## Backup scope

Back up every table matching `src_phone_%`. Backing up only `src_phone_data` does not preserve messages, social content, MyCloud links, wallet state, routers, or cellular plans.

Never include `shared/server_config.lua` or API credentials in a database dump or support attachment.