504 lines
6.2 KiB
Markdown
504 lines
6.2 KiB
Markdown
# DATABASES.md
|
|
|
|
# BZOD Database Architecture
|
|
|
|
BZOD v0.5.1 uses SQLite exclusively.
|
|
|
|
Rather than using a single monolithic database, BZOD separates data into administrative and tenant-specific databases. This architecture improves security, isolation, backup flexibility, disaster recovery, and scalability.
|
|
|
|
---
|
|
|
|
# Overview
|
|
|
|
BZOD stores data in the following structure:
|
|
|
|
```text
|
|
data/
|
|
├── admin/
|
|
│ ├── admin.db
|
|
│ ├── system.db
|
|
│ └── users.db
|
|
│
|
|
└── users/
|
|
├── 1/
|
|
│ ├── analytics.db
|
|
│ ├── content.db
|
|
│ └── profile.db
|
|
│
|
|
├── 2/
|
|
│ ├── analytics.db
|
|
│ ├── content.db
|
|
│ └── profile.db
|
|
│
|
|
└── N/
|
|
├── analytics.db
|
|
├── content.db
|
|
└── profile.db
|
|
```
|
|
|
|
Each user receives isolated databases.
|
|
|
|
No user content or analytics are stored in the central administrative databases.
|
|
|
|
---
|
|
|
|
# Administrative Databases
|
|
|
|
Administrative databases are located under:
|
|
|
|
```text
|
|
data/admin/
|
|
```
|
|
|
|
---
|
|
|
|
# users.db
|
|
|
|
Primary authentication and user management database.
|
|
|
|
Purpose:
|
|
|
|
* User accounts
|
|
* Password hashes
|
|
* Sessions
|
|
* Quotas
|
|
* API tokens
|
|
* User status tracking
|
|
|
|
Typical tables:
|
|
|
|
```text
|
|
users
|
|
sessions
|
|
quotas
|
|
api_tokens
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
* Authentication
|
|
* Authorization
|
|
* Session management
|
|
* Account status
|
|
* Quota enforcement
|
|
|
|
This is the primary identity database of the platform.
|
|
|
|
---
|
|
|
|
# system.db
|
|
|
|
Global platform database.
|
|
|
|
Purpose:
|
|
|
|
* Global slug namespace
|
|
* Moderation
|
|
* Auditing
|
|
* System configuration
|
|
|
|
Typical tables:
|
|
|
|
```text
|
|
global_slugs
|
|
slug_history
|
|
moderation_events
|
|
audit_events
|
|
reserved_slugs
|
|
settings
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
* Global slug uniqueness
|
|
* Slug ownership
|
|
* Moderation actions
|
|
* Audit logging
|
|
* System settings
|
|
|
|
Every redirect ultimately resolves through records stored in this database.
|
|
|
|
---
|
|
|
|
# admin.db
|
|
|
|
Administrative application database.
|
|
|
|
Purpose:
|
|
|
|
* Administrative metadata
|
|
* Administrative API key records
|
|
* Legacy compatibility structures
|
|
* Internal management data
|
|
|
|
Typical tables:
|
|
|
|
```text
|
|
api_keys
|
|
audit_events
|
|
```
|
|
|
|
This database is reserved for administrative functions and does not store tenant content.
|
|
|
|
---
|
|
|
|
# Tenant Databases
|
|
|
|
Tenant databases are located under:
|
|
|
|
```text
|
|
data/users/{user_id}/
|
|
```
|
|
|
|
Each user owns a completely isolated set of databases.
|
|
|
|
Example:
|
|
|
|
```text
|
|
data/users/2/
|
|
├── analytics.db
|
|
├── content.db
|
|
└── profile.db
|
|
```
|
|
|
|
---
|
|
|
|
# content.db
|
|
|
|
Stores user-owned content.
|
|
|
|
Purpose:
|
|
|
|
* Short URLs
|
|
* Landing pages
|
|
* QR metadata
|
|
* Preview metadata
|
|
|
|
Typical tables:
|
|
|
|
```text
|
|
urls
|
|
pages
|
|
qr_codes
|
|
previews
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
* URL management
|
|
* Landing page management
|
|
* Content ownership
|
|
|
|
This database contains the actual resources owned by a user.
|
|
|
|
---
|
|
|
|
# analytics.db
|
|
|
|
Stores traffic and visitor information.
|
|
|
|
Purpose:
|
|
|
|
* Visit recording
|
|
* Referrer tracking
|
|
* Browser tracking
|
|
* Country statistics
|
|
* Aggregated analytics
|
|
|
|
Typical tables:
|
|
|
|
```text
|
|
visits
|
|
referrers
|
|
browsers
|
|
countries
|
|
daily_stats
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
* Analytics collection
|
|
* Reporting
|
|
* Dashboard statistics
|
|
|
|
Analytics are fully isolated per user.
|
|
|
|
Administrators access aggregated analytics by querying each user's analytics database.
|
|
|
|
---
|
|
|
|
# profile.db
|
|
|
|
Stores user-specific profile information.
|
|
|
|
Purpose:
|
|
|
|
* User preferences
|
|
* Profile settings
|
|
* Future extensible metadata
|
|
|
|
Typical tables:
|
|
|
|
```text
|
|
profile
|
|
preferences
|
|
```
|
|
|
|
Responsibilities:
|
|
|
|
* User profile management
|
|
* Dashboard preferences
|
|
* Future personalization features
|
|
|
|
---
|
|
|
|
# Database Isolation Model
|
|
|
|
BZOD follows a strict tenant isolation model.
|
|
|
|
```text
|
|
User A
|
|
├── content.db
|
|
├── analytics.db
|
|
└── profile.db
|
|
|
|
User B
|
|
├── content.db
|
|
├── analytics.db
|
|
└── profile.db
|
|
```
|
|
|
|
User databases never share tables.
|
|
|
|
Cross-user content access is prevented by design.
|
|
|
|
Benefits:
|
|
|
|
* Security
|
|
* Easier backups
|
|
* Easier deletion
|
|
* Reduced corruption impact
|
|
|
|
---
|
|
|
|
# Global Slug Registry
|
|
|
|
The system maintains a single namespace.
|
|
|
|
Stored in:
|
|
|
|
```text
|
|
system.db
|
|
```
|
|
|
|
Table:
|
|
|
|
```text
|
|
global_slugs
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
abc123 → User 2 URL
|
|
docs → User 5 Page
|
|
demo → User 1 URL
|
|
```
|
|
|
|
This guarantees:
|
|
|
|
* Global uniqueness
|
|
* Ownership tracking
|
|
* Moderation support
|
|
* Slug transfer support
|
|
|
|
---
|
|
|
|
# Write Flow
|
|
|
|
Creating a URL:
|
|
|
|
```text
|
|
1. Validate quota
|
|
2. Register slug in system.db
|
|
3. Create URL in content.db
|
|
4. Update quota counters
|
|
5. Write audit event
|
|
```
|
|
|
|
Creating a landing page:
|
|
|
|
```text
|
|
1. Validate quota
|
|
2. Register slug in system.db
|
|
3. Create page in content.db
|
|
4. Update quota counters
|
|
5. Write audit event
|
|
```
|
|
|
|
---
|
|
|
|
# Analytics Flow
|
|
|
|
Visitor request:
|
|
|
|
```text
|
|
GET /abc123
|
|
```
|
|
|
|
Process:
|
|
|
|
```text
|
|
global_slugs
|
|
↓
|
|
content.db lookup
|
|
↓
|
|
redirect
|
|
↓
|
|
analytics.db visit record
|
|
```
|
|
|
|
Analytics writes never modify content records.
|
|
|
|
---
|
|
|
|
# WAL Mode
|
|
|
|
All databases operate in SQLite WAL mode.
|
|
|
|
Verify:
|
|
|
|
```sql
|
|
PRAGMA journal_mode;
|
|
```
|
|
|
|
Expected:
|
|
|
|
```text
|
|
wal
|
|
```
|
|
|
|
Benefits:
|
|
|
|
* Improved concurrency
|
|
* Reduced write contention
|
|
* Crash recovery
|
|
|
|
Associated files:
|
|
|
|
```text
|
|
*.db
|
|
*.db-shm
|
|
*.db-wal
|
|
```
|
|
|
|
---
|
|
|
|
# WAL Checkpointing
|
|
|
|
Large WAL files are normal during heavy traffic.
|
|
|
|
Example:
|
|
|
|
```text
|
|
analytics.db-wal
|
|
content.db-wal
|
|
```
|
|
|
|
To manually checkpoint:
|
|
|
|
```sql
|
|
PRAGMA wal_checkpoint(TRUNCATE);
|
|
```
|
|
|
|
The healthcheck and backup jobs may trigger checkpoints automatically.
|
|
|
|
---
|
|
|
|
# Backups
|
|
|
|
Recommended:
|
|
|
|
```bash
|
|
bzod backup
|
|
```
|
|
|
|
This creates a consistent archive of:
|
|
|
|
```text
|
|
admin/
|
|
users/
|
|
```
|
|
|
|
Never manually copy live databases while the application is running.
|
|
|
|
---
|
|
|
|
# Integrity Verification
|
|
|
|
Run:
|
|
|
|
```bash
|
|
bzod doctor
|
|
```
|
|
|
|
Or:
|
|
|
|
```sql
|
|
PRAGMA integrity_check;
|
|
```
|
|
|
|
Expected:
|
|
|
|
```text
|
|
ok
|
|
```
|
|
|
|
---
|
|
|
|
# Migration System
|
|
|
|
BZOD maintains schema versions using:
|
|
|
|
```sql
|
|
PRAGMA user_version;
|
|
```
|
|
|
|
Startup automatically executes:
|
|
|
|
```text
|
|
Db::init()
|
|
```
|
|
|
|
which:
|
|
|
|
1. Creates missing databases
|
|
2. Applies migrations
|
|
3. Validates schemas
|
|
4. Repairs legacy installations when required
|
|
|
|
---
|
|
|
|
# Design Principles
|
|
|
|
BZOD database architecture prioritizes:
|
|
|
|
* SQLite-only deployment
|
|
* Multi-user isolation
|
|
* Operational simplicity
|
|
* Backup friendliness
|
|
* Easy disaster recovery
|
|
* Minimal dependencies
|
|
* Single-binary deployment
|
|
|
|
---
|
|
|
|
# Related Documentation
|
|
|
|
* ARCHITECTURE.md
|
|
* MULTI_USER.md
|
|
* BACKUP_RESTORE.md
|
|
* INSTALL.md
|
|
* UPGRADE.md
|
|
* SECURITY.md
|