Backup and Restore Data

This guide covers backing up your database, restoring from backups, and managing data for migrations or cleanup.

Caution

Data operations are permanent. Always export a backup before clearing or modifying data.

---

Creating Backups

Regular backups protect against data loss and enable safe testing.

Full Database Backup

Export all tables in a single file:

1. Navigate to Admin Dashboard → Data Management
2. Click Export Full Database
3. File downloads automatically as mlsgrid-full-export-YYYY-MM-DD.json
4. Store in a secure location outside the server

What’s included:

• Brokers
• Agents
• Tours
• Suggestions
• API Keys
• Metadata (export timestamp, table information)

Tip

Schedule weekly full backups before major updates or configuration changes.

---

Individual Table Export

Export specific tables when you only need partial data:

1. Navigate to Admin Dashboard → Data Management
2. Click the export button for the desired table:
   • Export Brokers
   • Export Agents
   • Export Tours
   • Export Suggestions
   • Export API Keys
3. File downloads as mlsgrid-{table}-YYYY-MM-DD.json

When to use:

• Backing up before modifying specific records
• Sharing agent data with another admin
• Archiving old tour requests

---

Backup Best Practices

Regular Schedule

Weekly full backups

Daily exports of critical tables (agents, brokers)

Secure Storage

Store backups outside the server

Use encrypted cloud storage or external drives

Test Restoration

Periodically verify backups work

Import into a test environment monthly

Retention Policy

Keep 4 weekly backups

Keep 12 monthly backups (first of each month)

---

Restoring from Backup

Import previously exported data to restore records.

Restoring a Full Backup

1. Navigate to Admin Dashboard → Data Management
2. Click Import from File
3. Drag the backup JSON file into the upload zone (or click to browse)
4. Import Target automatically detects “All Tables”
5. Optional: Enable “Clear existing data” to replace all records
6. Click Import Data
7. Review the import summary when complete

Caution

Enabling “Clear existing data” deletes all current records before importing. This cannot be undone.

---

Restoring a Single Table

1. Navigate to Admin Dashboard → Data Management
2. Click Import from File
3. Select your single-table export file
4. Import Target auto-detects the table (or select manually)
5. Optional: Enable “Clear existing data” to replace records in that table only
6. Click Import Data

Import behavior:

• Without “Clear existing data”: New records are added, duplicates are skipped
• With “Clear existing data”: Table is emptied, then all records from file are imported

---

Understanding Import Results

After import completes, you’ll see a summary:

Result Field	Description
Total Records Imported	Successfully added records
Records Skipped	Duplicates (records with existing IDs)
Errors Encountered	Failed imports (invalid data, constraint violations)
Processing Time	Duration of the import operation

Tip

If you see many skipped records, the data may already exist. Check the “Clear existing data” option to replace instead of merge.

---

Migration Workflow

Moving data between environments (development, staging, production):

Migrating to a New Environment

1. Export from source:
   • Export full database from the source environment
   • Store the file securely
2. Prepare target:
   • Ensure target environment has the same schema version
   • Back up any existing data in target (if needed)
3. Import to target:
   • Upload the export file
   • Enable “Clear existing data” to replace all records
   • Import data
4. Verify:
   • Check record counts match source
   • Test key functionality (authentication, search, admin access)
   • Review Recent Activity logs for errors
5. Clean up:
   • Delete export file from source (if sensitive)
   • Document the migration

---

Partial Data Migration

Moving only specific records (e.g., testing with subset of production data):

1. Export from source:
   • Export only the tables you need
2. Import to target:
   • Import each table file individually
   • Do not enable “Clear existing data” (merge with existing records)
3. Verify:
   • Check that the specific records are present
   • Test functionality involving those records

---

Clearing Data

Remove records when you need to reset a table or the entire database.

Clearing Individual Tables

1. Navigate to Admin Dashboard → Data Management
2. Scroll to Clear Data section
3. Click the clear button for the desired table:
   • Clear Brokers
   • Clear Agents
   • Clear Tours
   • Clear Suggestions
   • Clear API Keys
4. Type the table name in UPPERCASE to confirm (e.g., AGENTS)
5. Click Confirm

Danger

Clearing data is permanent and cannot be undone. Always export a backup first.

---

Clearing All Tables

Complete database reset (use with extreme caution):

1. Export a full backup first (mandatory)
2. Navigate to Admin Dashboard → Data Management
3. Click Clear All Tables
4. Type DELETE to confirm
5. Click Confirm
6. All records in all tables are permanently deleted

When to use:

• Resetting a development environment
• Starting fresh after a test migration
• Clearing corrupted data before re-import

Never use in production unless you have a verified backup and a disaster recovery plan.

---

Troubleshooting

Import Fails with “Invalid JSON”

Cause: The file is corrupted or not valid JSON

Solution:

1. Open the file in a text editor
2. Verify it starts with { or [ and ends with } or ]
3. Use a JSON validator (e.g., jsonlint.com) to check syntax
4. If corrupted, restore from a backup of the backup

---

Import Shows Many Errors

Cause: Data format doesn’t match current schema

Solutions:

• Verify the export came from a compatible version
• Check for missing required fields in the data
• Review database migrations (schema may have changed)
• If schema changed, manually edit the JSON to add missing fields

---

Statistics Not Loading

Cause: Authentication issue or API service down

Solutions:

1. Verify you’re logged in as an admin
2. Check Dashboard → API Services for service health
3. Try clicking the Refresh button
4. If still failing, check browser console for errors
5. Reload the page

---

Clear Confirmation Not Working

Cause: Incorrect confirmation text

Solutions:

• For individual tables, type the table name in UPPERCASE exactly (e.g., AGENTS not agents)
• For full database clear, type DELETE exactly (not delete or Delete)
• Copy and paste from the prompt if uncertain

---

Advanced Workflows

Selective Data Updates

Updating specific records without clearing everything:

1. Export the table containing records to update
2. Edit the JSON file:
   • Modify the specific records you want to change
   • Keep IDs the same (so they update existing records)
3. Import the file without “Clear existing data”
4. Records with matching IDs are updated, others are skipped

Note

This workflow depends on database behavior. Test in a non-production environment first.

---

Merging Data from Multiple Sources

Combining data from different exports:

1. Export from source A (e.g., staging)
2. Export from source B (e.g., production)
3. Import source A into target
4. Import source B into target without “Clear existing data”
5. Duplicates (same IDs) are skipped, unique records are added
6. Review record counts to verify expected totals

---

Related Documentation

• Data Management Reference — Table descriptions and formats
• Monitor System Health — Troubleshooting failures