Missing macOS ARM64 Native Library in System.Data.SQLite.Core NuGet Package

System.Data.SQLite.Core macOS M1/ARM64 Compatibility Challenges

Issue Overview: Absence of ARM64 Native Interop in SQLite.Core NuGet Packages

The core problem stems from the System.Data.SQLite.Core NuGet package lacking precompiled native libraries (SQLite.Interop.dll) for macOS ARM64 (M1/M2/M3 chips). This omission prevents applications relying on this package from functioning natively on Apple Silicon devices. When developers target macOS ARM64 platforms, the runtime fails to locate a compatible native SQLite binary, resulting in DllNotFoundException or BadImageFormatException errors.

The System.Data.SQLite library uses a hybrid architecture: managed .NET assemblies (e.g., System.Data.SQLite.dll) depend on platform-specific native libraries (SQLite.Interop.dll). These native binaries are stored in NuGet package subdirectories like runtimes/linux-x64/native, runtimes/win-x64/native, and runtimes/osx-x64/native. The absence of runtimes/osx-arm64/native forces applications to rely on x64 emulation via Rosetta 2, which introduces performance penalties and compatibility risks.

Microsoft’s Microsoft.Data.Sqlite package avoids this issue by leveraging .NET’s built-in SQLite dependency resolution, which dynamically retrieves platform-appropriate SQLite binaries. However, System.Data.SQLite remains critical for legacy applications requiring ADO.NET compatibility, advanced configuration, or features like Full-Text Search (FTS5).

The discussion highlights three critical pain points:

1. Build Toolchain Limitations: The official build process for System.Data.SQLite.Core does not include macOS ARM64 as a target.
2. Entrypoint Mismatches: Custom-compiled ARM64 binaries may fail due to symbol name mismatches (mangled vs. unmangled entrypoints).
3. NuGet Package Structure: Developers cannot easily extend the package with custom native libraries without breaking version compatibility.

Possible Causes of macOS ARM64 Support Gaps

1. Build Pipeline Configuration for Multi-Architecture Targets

The System.Data.SQLite compilation scripts (compile-interop-assembly-release.sh) historically hardcode x86_64 architecture flags (-arch x86_64). This setup excludes ARM64 builds, as no equivalent -arch arm64 flag is present. Without cross-compilation support or dedicated ARM64 build agents, the pipeline cannot generate macOS ARM64 binaries.

2. Symbol Mangling Incompatibilities

The native SQLite.Interop.dll uses C-style symbol mangling for exported functions (e.g., sqlite3_open becomes _sqlite3_open). When developers compile custom ARM64 binaries, mismatches arise if the managed assembly expects unmangled symbols. This is tied to the SQLITE_INTEROP_FUNCTIONS macro in Interop.cs, which must align with the native library’s exported symbols. Version 1.0.115 introduced stricter symbol validation, breaking third-party binaries.

3. NuGet Package Versioning Constraints

NuGet’s dependency resolution enforces strict version matching between the managed assembly (System.Data.SQLite.Core) and native interop libraries. Even if a developer compiles an ARM64-native SQLite.Interop.dll, placing it in runtimes/osx-arm64/native will fail unless the managed assembly is rebuilt with matching version metadata. The official package’s strong naming further complicates forks or community patches.

4. Maintainer Resource Limitations

The SQLite team’s response indicates limited access to ARM64 macOS hardware for testing and validation. Building and validating ARM64 binaries requires:

• macOS ARM64 CI/CD infrastructure
• Updates to the Makefile and configure scripts
• Validation against the SQLite test suite (e.g., make test)

Without these resources, ARM64 support remains speculative.

Troubleshooting Steps, Solutions & Fixes

1. Validate Current Package Support

First, confirm whether your application’s target runtime is correctly configured. For .NET 6+ projects, ensure the <RuntimeIdentifiers> tag includes osx-arm64:

<PropertyGroup>  
  <RuntimeIdentifier>osx-arm64</RuntimeIdentifier>  
</PropertyGroup>  

If the NuGet package lacks an osx-arm64 directory, the runtime falls back to x64 emulation. To detect this, enable native loading logs:

SQLiteLog.Initialize();  
SQLiteLog.AddListener(new ConsoleSQLiteLogListener());  

A log entry like "Failed to load native interop library for RuntimeIdentifier=osx-arm64" confirms the missing ARM64 binary.

2. Migrate to Microsoft.Data.Sqlite

For new projects or non-ADO.NET-dependent codebases, Microsoft.Data.Sqlite is a robust alternative. It uses .NET’s native dependency resolution, which automatically loads libsqlite3.dylib from system paths or app-local directories. To ensure ARM64 compatibility:

# Install the system SQLite library via Homebrew  
brew install sqlite3  

In your project:

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

Note that Microsoft.Data.Sqlite lacks certain features like virtual table modules.

3. Compile SQLite.Interop.dll for macOS ARM64

To build a custom ARM64-native interop library:

Step 1: Clone the SQLite Source

git clone https://github.com/sqlite/sqlite  
cd sqlite  

Step 2: Modify Compilation Flags
Edit Setup/compile-interop-assembly-release.sh, replacing -arch x86_64 with -arch arm64:

gccflags="-arch arm64 -fPIC -DPIC -DSQLITE_ENABLE_COLUMN_METADATA"  

Step 3: Build the Native Library

./configure --enable-debug=no --enable-rtree --enable-fts5  
make  

Copy the generated SQLite.Interop.dll to runtimes/osx-arm64/native in your project.

4. Align Managed and Native Entrypoints

If symbol mismatches occur, rebuild the managed assembly (System.Data.SQLite.Core) from source:

Step 1: Clone the System.Data.SQLite Repository

git clone https://github.com/sqlitebrowser/sqlite-netFx  

Step 2: Update Interop.cs
Ensure SQLITE_INTEROP_FUNCTIONS matches the native library’s exported symbols. Use nm SQLite.Interop.dll to list symbols:

nm -gU SQLite.Interop.dll | grep sqlite3  

Step 3: Rebuild with ARM64 Support
Modify SQLite.NET.Source.2015.sln to include ARM64 build configurations. Reference the custom SQLite.Interop.dll during linking.

5. Use Community-Patched NuGet Packages

Unofficial packages like System.Data.SQLite.Core.osx.arm64 provide ARM64 binaries. However, these may lag behind official releases. To integrate:

<PackageReference Include="System.Data.SQLite.Core.osx.arm64" Version="1.0.117" />  

Add conditional references for other platforms:

<ItemGroup Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">  
  <PackageReference Include="System.Data.SQLite.Core.osx.arm64" Version="1.0.117" />  
</ItemGroup>  

6. Advocate for Official ARM64 Support

Engage with the SQLite team via:

• Forum Threads: Highlight use cases requiring ARM64 support.
• GitHub Issues: File detailed requests in sqlitebrowser/sqlite-netFx.
• Sponsorship: Contribute to funding ARM64 CI/CD infrastructure.

7. Rosetta 2 Fallback

As a last resort, force x64 emulation:

# Launch app under Rosetta 2  
arch -x86_64 dotnet run  

Configure the project to target osx-x64:

<RuntimeIdentifier>osx-x64</RuntimeIdentifier>  

By addressing build pipeline gaps, aligning symbol exports, and leveraging community resources, developers can bridge the macOS ARM64 compatibility gap in System.Data.SQLite.Core. Until official support materializes, hybrid approaches combining custom compilations and NuGet workarounds offer viable paths forward.