pgsql-jellyfin/docs/SQLITE_REMOVAL_PLAN.md

Removing SQLite from PostgreSQL-Only Deployment

Date: 2026-02-26
Status: 📋 Plan Ready
Goal: Remove SQLite dependencies from PostgreSQL-focused deployment

---

Overview

Since this fork is PostgreSQL-focused, we can remove SQLite components to:

• ✅ Reduce deployment size
• ✅ Clarify PostgreSQL-only focus
• ✅ Remove unnecessary dependencies
• ✅ Simplify build and maintenance

---

What Can Be Removed

1. SQLite Provider Project ❌

src/Jellyfin.Database/Jellyfin.Database.Providers.Sqlite/

• Size: 80+ migration files, provider implementation
• Used for: SQLite database support
• Can remove: Yes (PostgreSQL-only fork)

2. SQLite NuGet Packages ❌

• Microsoft.EntityFrameworkCore.Sqlite (in Sqlite provider)
• Microsoft.Data.Sqlite (in Emby.Server.Implementations)

3. Project References ❌

• Jellyfin.Server.Implementations → SQLite provider
• Any test projects referencing SQLite

---

Current SQLite References

Files Containing SQLite References

1. Jellyfin.Server.Implementations.csproj

   <ProjectReference Include="..\src\Jellyfin.Database\Jellyfin.Database.Providers.Sqlite\Jellyfin.Database.Providers.Sqlite.csproj" />
   

2. Emby.Server.Implementations.csproj

   <PackageReference Include="Microsoft.Data.Sqlite" />
   

3. Jellyfin.Database.Providers.Sqlite.csproj

   <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" />
   

---

Decision: Keep or Remove?

Option 1: Remove Completely (Recommended for PostgreSQL-Only Fork) ✅

Pros:

• ✅ Smaller deployment (~10-20MB less)
• ✅ Clear PostgreSQL-only focus
• ✅ No SQLite DLLs in output
• ✅ Simpler maintenance

Cons:

• ❌ No SQLite migration path
• ❌ Breaking change for SQLite users
• ❌ Can't fall back to SQLite

Recommendation: ✅ Remove it - This is a PostgreSQL fork, not a multi-database fork

Option 2: Keep for Migration Support (Not Recommended)

Pros:

• ✅ Can migrate from SQLite
• ✅ Backward compatibility

Cons:

• ❌ Larger deployment
• ❌ Confusing messaging
• ❌ Maintenance burden

Recommendation: ❌ Migration can be done separately with tooling

---

Removal Strategy

Phase 1: Remove SQLite Provider from Deployment ✅

Action: Exclude SQLite from publish without removing project

Benefits:

• Deployment doesn't include SQLite DLLs
• Source code remains for reference
• Can still build if needed

Implementation:

<!-- In Jellyfin.Server.csproj or publish profile -->
<ItemGroup>
  <ProjectReference Include="..\Jellyfin.Server.Implementations\Jellyfin.Server.Implementations.csproj">
    <ExcludeFromPublish>true</ExcludeFromPublish> <!-- If contains SQLite -->
  </ProjectReference>
</ItemGroup>

Phase 2: Remove SQLite Project Reference (Recommended) ✅

Action: Remove project reference from Jellyfin.Server.Implementations

Implementation: See detailed steps below

Phase 3: Remove SQLite Project Entirely (Optional)

Action: Delete the entire SQLite provider project

When: After confirming Phase 2 works in production

---

Implementation Steps

Step 1: Backup Current State

git checkout -b remove-sqlite
git commit -m "Checkpoint before removing SQLite"

Step 2: Remove SQLite Project Reference

File: Jellyfin.Server.Implementations/Jellyfin.Server.Implementations.csproj

<!-- REMOVE THIS LINE -->
<ProjectReference Include="..\src\Jellyfin.Database\Jellyfin.Database.Providers.Sqlite\Jellyfin.Database.Providers.Sqlite.csproj" />

Step 3: Remove SQLite Package from Emby

File: Emby.Server.Implementations/Emby.Server.Implementations.csproj

Check if Microsoft.Data.Sqlite is actually used:

# Search for SQLite usage
grep -r "Microsoft.Data.Sqlite" Emby.Server.Implementations/

If not used, remove:

<!-- REMOVE THIS LINE -->
<PackageReference Include="Microsoft.Data.Sqlite" />

Step 4: Update Solution File (Optional)

File: Jellyfin.sln

Consider removing SQLite provider project from solution:

# Comment out or remove
# Project("{...}") = "Jellyfin.Database.Providers.Sqlite", "src\Jellyfin.Database\Jellyfin.Database.Providers.Sqlite\Jellyfin.Database.Providers.Sqlite.csproj", "{...}"

Step 5: Exclude from Build

File: Directory.Build.props or individual project

<PropertyGroup>
  <!-- Exclude SQLite provider from build -->
  <DefaultItemExcludes>$(DefaultItemExcludes);**/Jellyfin.Database.Providers.Sqlite/**</DefaultItemExcludes>
</PropertyGroup>

Step 6: Update Publish Profile

File: Publish profiles or Jellyfin.Server.csproj

<PropertyGroup>
  <!-- Explicitly exclude SQLite DLLs -->
  <ExcludeAssets>Microsoft.EntityFrameworkCore.Sqlite;Microsoft.Data.Sqlite</ExcludeAssets>
</PropertyGroup>

Step 7: Test Build

# Clean build
dotnet clean
rm -rf lib/

# Build without SQLite
dotnet build --configuration Release

# Verify no SQLite DLLs
Get-ChildItem lib/Release/net11.0 -Filter "*Sqlite*"
# Should return nothing

Step 8: Test Deployment

# Publish
dotnet publish Jellyfin.Server --configuration Release -o publish/

# Check for SQLite
Get-ChildItem publish/ -Filter "*Sqlite*" -Recurse
# Should return nothing

# Verify size reduction
# Before: ~XXX MB
# After: ~YYY MB (should be smaller)

---

Code Changes Needed

1. Remove SQLite Database Provider Registration

File: Look for SQLite provider registration (likely in Startup or ServiceCollection)

Search for:

services.AddDbContext<JellyfinDb>(options => 
    options.UseSqlite(...)
);

Or:

DatabaseProvider.Sqlite
case "Sqlite":

Action: Remove SQLite-specific code paths

2. Update Database Provider Enum/Options

If there's a database provider enum or config:

public enum DatabaseProvider
{
    // Remove this:
    // Sqlite,
    Postgres
}

3. Update Startup Configuration Validation

// Remove SQLite validation
if (provider == "Sqlite")
{
    throw new InvalidOperationException("SQLite is not supported. Use PostgreSQL.");
}

---

Verification Checklist

After removal, verify:

• Build succeeds without errors
• No *Sqlite*.dll files in lib/Release/net11.0/
• No *Sqlite*.dll files in published output
• Application starts successfully
• PostgreSQL connection works
• No SQLite references in startup logs
• Deployment size reduced
• Installer doesn't include SQLite

Check Build Output

# Search for SQLite DLLs
Get-ChildItem lib/ -Recurse -Filter "*Sqlite*"
Get-ChildItem lib/ -Recurse -Filter "*SQLite*"

# Should return nothing or only test assemblies

Check Runtime Logs

# Start Jellyfin
cd lib/Release/net11.0
dotnet jellyfin.dll

# Check logs for SQLite references
grep -i sqlite log/*.txt
# Should return nothing

---

Deployment Size Reduction

Expected Savings

SQLite DLLs:

• Microsoft.EntityFrameworkCore.Sqlite.dll ~150 KB
• Microsoft.Data.Sqlite.dll ~400 KB
• SQLitePCLRaw.*.dll (multiple) ~2-5 MB
• e_sqlite3.dll (native) ~2-3 MB

Total Expected Savings: ~5-10 MB

Plus:

• Fewer dependencies to manage
• Smaller Docker images
• Faster downloads

---

Migration Support (Alternative Approach)

If you want to support SQLite → PostgreSQL migration without including SQLite in runtime:

Option A: Separate Migration Tool

Create a separate tool: Jellyfin.MigrationTool

# Separate executable with SQLite support
dotnet run --project Jellyfin.MigrationTool -- --from-sqlite jellyfin.db --to-postgres "Host=..."

Benefits:

• SQLite only in migration tool
• Runtime deployment stays clean
• Clear separation of concerns

Option B: Documentation-Only

Document how to migrate using PostgreSQL tools:

## Migrating from SQLite

1. Export SQLite data to SQL/CSV
2. Import into PostgreSQL using pg_restore or COPY
3. Start PostgreSQL-enabled Jellyfin

Recommendation: ✅ Use Option B (documentation)

---

Update Documentation

Files to Update

1. README.md

   ## Database Support
   
   This fork uses **PostgreSQL only**. SQLite is not supported.
   
   For migration from SQLite, see [MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md)
   

2. INSTALLER_GUIDE.md

   • Remove any SQLite references
   • Emphasize PostgreSQL requirement

3. QUICKSTART_POSTGRESQL.md

   • Make it clear: PostgreSQL only
   • No SQLite fallback

4. New: SQLITE_REMOVAL.md

   • Why SQLite was removed
   • Migration options
   • Alternative tools

---

Git Commit Message

git add .
git commit -m "Remove SQLite support for PostgreSQL-only deployment

- Removed Jellyfin.Database.Providers.Sqlite project reference
- Removed Microsoft.Data.Sqlite package from Emby.Server.Implementations
- Excluded SQLite DLLs from build and publish
- Updated documentation to reflect PostgreSQL-only support
- Deployment size reduced by ~5-10 MB

Breaking Change: SQLite database backend is no longer supported
Migration: Use PostgreSQL migration tools or separate migration utility

Reason: This fork is PostgreSQL-focused. Removing SQLite:
- Reduces deployment size
- Simplifies maintenance
- Clarifies project focus
- Removes unnecessary dependencies
"

---

Testing Plan

Test Scenarios

1. Fresh Install (PostgreSQL)

   • Install on clean system
   • Configure PostgreSQL
   • Verify no SQLite DLLs
   • Confirm application works

2. Build Test

   • Clean build from scratch
   • No compilation errors
   • No SQLite DLLs in output

3. Publish Test

   • Publish to folder
   • Check deployment size
   • Verify no SQLite files

4. Installer Test

   • Build installer
   • Install on test system
   • Verify PostgreSQL-only

5. Runtime Test

   • Start application
   • Check logs (no SQLite references)
   • Database operations work

---

Rollback Plan

If removal causes issues:

# Revert changes
git checkout pgsql_testing_branch

# Or cherry-pick specific commits
git cherry-pick <commit-hash>

---

Recommendation

✅ Remove SQLite Completely

Why:

1. This is a PostgreSQL fork - be explicit
2. Reduces confusion for users
3. Smaller deployment size
4. Easier maintenance
5. Clear project focus

How:

1. Remove project reference (Phase 2)
2. Test thoroughly
3. Update documentation
4. Commit with clear message

When:

• After thorough testing
• Include in next PR
• Document breaking change

---

Summary

Current State:

• SQLite provider project exists
• SQLite packages referenced
• SQLite DLLs in deployment

Proposed State:

• No SQLite provider
• No SQLite packages
• PostgreSQL only
• 5-10 MB smaller deployment

Impact:

• Breaking change for SQLite users
• Clearer PostgreSQL focus
• Simpler codebase
• Better performance

Status: 📋 Ready to implement
Risk: Low (PostgreSQL fork)
Benefit: High (clarity and size)
Recommendation: ✅ Proceed with removal

---

Next Steps:

1. Review this plan
2. Test SQLite removal in development
3. Update documentation
4. Include in next commit/PR
5. Announce breaking change clearly