# Local Database Migration Specification

## Overview

This document specifies the automatic path migration process for transferring an Audiobookshelf database from a Docker deployment to a local development environment.

## Problem Statement

The source database was created in a Docker container environment with hardcoded absolute paths. These paths must be automatically detected and remapped to match the local development environment structure.

## Source Database

- **Location**: `/mnt/docker/work/books/audiobookshelf/config/absdatabase.sqlite`
- **Version**: 2.32.1 (from settings)

## Identified Path References

### 1. libraryFolders Table

**Table**: `libraryFolders` **Columns with paths**: `path`

**Sample data**: | id | path | libraryId | |----|------|-----------| | 9f980819-1371-4c8f-9e7d-a6cbe9ae1ba7 | /audiobooks | a04cbf28-7eb6-4c87-b3e3-421ad8b35923 | | 43bf8c8d-07b6-4828-848f-8bb1e3dcca04 | /libraries/books | dad4448d-77c2-481e-9212-1ffcb4272932 |

**Migration strategy**:

- Map each unique library folder path to a corresponding local path
- Preserve the folder structure within each library

### 2. libraryItems Table

**Table**: `libraryItems` **Columns with paths**: `path`, `relPath`

**Sample data**: | id | path | relPath | title | |----|------|---------|-------| | 6ec745f9-608e-4556-8f78-b36e2682069b | /audiobooks/A Beginner's Guide to Forever.m4b | A Beginner's Guide to Forever.m4b | A Beginner's Guide to Forever |

**Migration strategy**:

- The `path` column contains full absolute paths from Docker root
- The `relPath` column contains paths relative to library folder (less likely to need migration)
- Update `path` to use local library folder mappings

### 3. books Table

**Table**: `books` **Columns with paths**: `coverPath`

**Sample data**: | id | coverPath | |----|-----------| | 68f4e9ca-c8e9-46a1-b667-7b0a409dd72d | /metadata/items/6ec745f9-608e-4556-8f78-b36e2682069b/cover.jpg |

**Migration strategy**:

- `coverPath` points to `/metadata/items/{libraryItemId}/cover.jpg`
- May need remapping if local `metadata` directory differs from Docker

### 4. feeds Table

**Table**: `feeds` **Columns with paths**: `serverAddress`, `feedURL`, `imageURL`, `siteURL`, `coverPath`

**Migration strategy**:

- `serverAddress`: The Docker container's server URL (e.g., `http://audiobookshelf:8080`)
- `feedURL`, `imageURL`, `siteURL`: URLs containing the server address
- `coverPath`: Local file path to feed cover images

### 5. settings Table

**Table**: `settings` **Key with paths**: `server-settings` (JSON value)

**Path settings in JSON**:

- `backupPath`: Docker path (e.g., `/metadata/backups`)
- Potentially others in nested JSON structure

## Migration Input/Output

### Input Mapping Format

```yaml
# path-mapping.yaml
libraries:
  /audiobooks: /home/user/audiobooks
  /libraries/books: /home/user/libraries/books
metadata:
  source: /metadata
  target: /home/user/audiobookshelf/metadata
server:
  docker_host: http://audiobookshelf:8080
  local_host: http://localhost:3333
```

### Output

- Modified SQLite database with all paths updated
- Migration log with changes made
- Backup of original database

## Validation Requirements

1. **Path format validation**: Ensure all updated paths follow local filesystem conventions
2. **Referential integrity**: Verify libraryItems reference valid libraryFolderIds
3. **URL validation**: Ensure feed URLs use correct local server address
4. **File existence check** (optional): Verify that mapped paths exist locally

## Implementation Phases

### Phase 1: Path Discovery

- [ ] Scan all tables for path-like values
- [ ] Identify all unique paths requiring migration
- [ ] Categorize paths by type (library folders, metadata, URLs)

### Phase 2: Mapping Configuration

- [ ] Create mapping configuration file
- [ ] Define library folder path mappings
- [ ] Define metadata path mappings
- [ ] Define server URL mappings

### Phase 3: Migration Script

- [ ] Implement path update logic for each table
- [ ] Implement URL update logic for feeds
- [ ] Implement settings path updates
- [ ] Add transaction safety with rollback capability

### Phase 4: Validation

- [ ] Run validation checks on migrated database
- [ ] Generate migration report
- [ ] Test database with local Audiobookshelf instance

## Related Files

- **Source database**: `/mnt/docker/work/books/audiobookshelf/config/absdatabase.sqlite`
- **Client config**: `/mnt/docker/work/books/audiobookshelf/client/nuxt.config.js`
- **Server config**: `/mnt/docker/work/books/audiobookshelf/server/Server.js`
- **Database models**: `/mnt/docker/work/books/audiobookshelf/server/models/`