Version: 0.8.0 Release Date: February 1, 2026

No database migrations are required for v0.8.0.

This release maintains 100% database compatibility with v0.7.0. The schema remains unchanged, and no data migrations are needed.

Conclusion: Database schema is identical.

# Connect to database
psql -h localhost -U postgres -d nchat

# Check schema version
SELECT * FROM schema_migrations ORDER BY version DESC LIMIT 1;

# Expected output: Latest migration from v0.7.0
# Example: 20250115_add_ai_features

Even though no migrations are needed, always backup before major upgrades:

# Full database backup
pg_dump -h localhost -U postgres -d nchat > backup-$(date +%Y%m%d).sql

# Compressed backup
pg_dump -h localhost -U postgres -d nchat | gzip > backup-$(date +%Y%m%d).sql.gz

# Custom format (for faster restore)
pg_dump -h localhost -U postgres -d nchat -Fc > backup-$(date +%Y%m%d).dump

# Check for pending migrations
cd .backend
nself db migrate status

# Expected output: "No pending migrations"

# Run database health check
nself db doctor

# Or manually verify
psql -h localhost -U postgres -d nchat

# Check all tables exist
\dt nchat_*

# Check table counts
SELECT
  schemaname,
  tablename,
  n_live_tup as row_count
FROM pg_stat_user_tables
WHERE schemaname = 'public'
ORDER BY tablename;

All existing data remains fully compatible:

• ✅ Users: All user data unchanged
• ✅ Messages: All messages unchanged
• ✅ Channels: All channels unchanged
• ✅ Files: All file references unchanged
• ✅ Settings: All settings unchanged
• ✅ Permissions: All permissions unchanged

v0.8.0 doesn't add any new database tables or columns. Mobile-specific data is stored in:

1. Client-side: IndexedDB for offline cache
2. Third-party: Firebase for analytics
3. Third-party: Sentry for crash reports

None of this data is stored in your PostgreSQL database.

Your existing AppConfig remains fully compatible:

// v0.7.0 config works unchanged in v0.8.0
interface AppConfig {
  setup: { ... }
  owner: { ... }
  branding: { ... }
  theme: { ... }
  features: { ... }
  integrations: { ... }
  // ... all other v0.7.0 fields
}

If you want to enable mobile features, you can optionally add:

interface AppConfig {
  // ... existing v0.7.0 fields ...

  // Optional: Mobile-specific config
  mobile?: {
    offlineCache: {
      enabled: boolean
      maxMessages: number // default: 1000
      maxMediaSize: number // default: 500 MB
    }
    backgroundSync: {
      enabled: boolean
      interval: number // minutes
    }
    analytics: {
      enabled: boolean
      firebaseConfig: {
        apiKey: string
        projectId: string
        // ...
      }
    }
  }
}

These are completely optional. Apps work without them.

File storage remains unchanged:

• Storage backend: Same (local, S3, MinIO, etc.)
• File paths: Same
• File metadata: Same
• Access control: Same

Mobile apps handle files transparently:

1. Upload: Mobile apps upload files to same backend as web
2. Download: Mobile apps download from same URLs
3. Cache: Mobile apps cache files locally (optional)
4. Sync: Mobile apps sync with same storage backend

No migration or data duplication.

User data structure remains identical:

-- Same user table structure
SELECT
  column_name,
  data_type,
  is_nullable
FROM information_schema.columns
WHERE table_name = 'nchat_users'
ORDER BY ordinal_position;

-- Output: Identical to v0.7.0

Mobile users authenticate the same way:

1. Login: Same authentication flow
2. Tokens: Same JWT tokens
3. Permissions: Same RBAC system
4. Sessions: Same session management

No changes to user authentication or authorization.

All API endpoints remain unchanged:

// v0.7.0 API calls work identically in v0.8.0

// GraphQL queries
query GetMessages($channelId: ID!) {
  messages(channelId: $channelId) {
    id
    text
    user { id name }
  }
}

// REST endpoints
GET /api/channels
POST /api/messages
PUT /api/users/:id
DELETE /api/messages/:id

// All work identically

New APIs added for mobile features:

// Optional: Offline sync API
POST / api / sync / queue
GET / api / sync / status

// Optional: Push notification registration
POST / api / push / register
DELETE / api / push / unregister

// These are additive, not required

If you need to rollback, it's simple (no database changes):

# 1. No database rollback needed
# (Schema unchanged, so no schema rollback)

# 2. Redeploy v0.7.0 application
git checkout v0.7.0
pnpm install
pnpm build
pnpm deploy

# 3. Verify rollback
curl https://your-domain.com/api/health
# Expected: {"status":"ok","version":"0.7.0"}

# 4. No data cleanup needed
# (No v0.8.0-specific data in database)

Mobile apps are independent:

1. iOS: Remove from App Store (or don't publish)
2. Android: Remove from Play Store (or don't publish)
3. Desktop: Remove from download links

Users on web continue working normally.

Test in staging before production:

# 1. Clone production database to staging
pg_dump -h prod-db -U postgres -d nchat | \
  psql -h staging-db -U postgres -d nchat

# 2. Deploy v0.8.0 to staging
git checkout v0.8.0
pnpm install
pnpm build
# Deploy to staging environment

# 3. Run integration tests
pnpm test:e2e

# 4. Verify all features work
# - Login
# - Send messages
# - Upload files
# - Search
# - Admin functions

# 5. Check database health
psql -h staging-db -U postgres -d nchat
SELECT COUNT(*) FROM nchat_messages;
SELECT COUNT(*) FROM nchat_channels;
SELECT COUNT(*) FROM nchat_users;

# 6. Verify data integrity
# - Check message counts match
# - Check user counts match
# - Check no data corruption

After production upgrade:

# 1. Verify database health
psql -h prod-db -U postgres -d nchat
SELECT COUNT(*) FROM nchat_messages;
# Compare to pre-upgrade count

# 2. Run smoke tests
curl https://your-domain.com/api/health
curl https://your-domain.com/api/channels

# 3. Test critical workflows
# - User login
# - Send message
# - Upload file
# - Search messages

# 4. Monitor logs
tail -f /var/log/nchat/application.log
# Or Docker logs, K8s logs, etc.

# 5. Check error rates
# - Application logs
# - Database logs
# - Sentry errors (if configured)

After migration, monitor:

1. Application Health

   • Response times
   • Error rates
   • Resource usage (CPU, memory)

2. Database Health

   • Query performance
   • Connection pool usage
   • Disk usage
   • Index usage

3. User Experience

   • Page load times
   • API response times
   • Error messages
   • User complaints

4. Mobile Apps (if deployed)

   • Crash rates
   • ANR (Android Not Responding)
   • Memory usage
   • Battery usage

-- Check database size
SELECT
  pg_size_pretty(pg_database_size('nchat')) as database_size;

-- Check table sizes
SELECT
  schemaname,
  tablename,
  pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as total_size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC
LIMIT 10;

-- Check slow queries
SELECT
  query,
  calls,
  total_time,
  mean_time,
  max_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- Check active connections
SELECT
  COUNT(*) as connection_count,
  state
FROM pg_stat_activity
WHERE datname = 'nchat'
GROUP BY state;

Symptom: Application can't connect to database after upgrade

Solution:

# Check database is running
pg_isready -h localhost -U postgres

# Check connection from app
psql -h localhost -U postgres -d nchat

# Verify connection string in .env
cat .env | grep DATABASE_URL

Symptom: Data appears to be missing after upgrade

Solution:

-- Verify data exists
SELECT COUNT(*) FROM nchat_messages;
SELECT COUNT(*) FROM nchat_users;
SELECT COUNT(*) FROM nchat_channels;

-- Check for soft-deleted records
SELECT COUNT(*) FROM nchat_messages WHERE deleted_at IS NOT NULL;

-- Restore from backup if needed
psql -h localhost -U postgres -d nchat < backup-20260201.sql

Symptom: Database queries are slow after upgrade

Solution:

-- Analyze tables
ANALYZE;

-- Vacuum tables
VACUUM ANALYZE;

-- Rebuild indexes
REINDEX DATABASE nchat;

-- Check for missing indexes
SELECT
  schemaname,
  tablename,
  attname,
  n_distinct,
  correlation
FROM pg_stats
WHERE schemaname = 'public'
  AND n_distinct > 100
ORDER BY n_distinct DESC;

Use this checklist for your migration:

• Read migration guide (this document)
• Verify no schema changes needed
• Backup production database
• Test in staging environment
• Document rollback procedure
• Schedule maintenance window (if needed)
• Notify team about upgrade

• Put application in maintenance mode (optional)
• Run migration check (nself db migrate status)
• Verify no pending migrations
• Deploy v0.8.0 application
• Verify application starts successfully
• Remove maintenance mode (if used)

• Verify database health
• Run smoke tests
• Test critical workflows
• Monitor logs for errors
• Check performance metrics
• Verify data integrity
• Notify team of successful upgrade

• Put in maintenance mode
• Redeploy v0.7.0 application
• Verify rollback successful
• Remove maintenance mode
• Document issues encountered
• Contact support if needed

A: No. v0.8.0 has zero database migrations. The schema is identical to v0.7.0.

A: No. All existing data remains unchanged and fully compatible.

A: There is no database migration, so it takes 0 seconds. Application deployment takes 5-10 minutes.

A: Yes, easily. Just redeploy v0.7.0. No database rollback needed.

A: No. Zero-downtime deployment is possible since there are no database changes.

A: Mobile apps use the same database as web. No separate data migration needed.

A: There's nothing to migrate. Offline cache is new in v0.8.0. It populates automatically.

A: No. Same database, same backup procedures.

A: Upgrade to v0.7.0 first, then to v0.8.0. See v0.7.0 migration guide for schema changes.

A: No. Database performance is identical to v0.7.0.

Need help with migration?

• Documentation: https://docs.nchat.io
• GitHub Issues: https://github.com/nself/nself-chat/issues
• Discord: https://discord.gg/nchat
• Email: [email protected]
• Slack: #nself-chat (for enterprise customers)

v0.8.0 Migration Summary:

✅ No database migrations required ✅ No schema changes ✅ No data changes ✅ No configuration migrations ✅ No file storage changes ✅ Zero-downtime deployment possible ✅ Simple rollback procedure ✅ 100% backward compatible

This is the easiest migration ever! 🎉

Questions? Contact [email protected]