Platform Selection

Velocity is available in six different NuGet packages, each tailored for specific licensing, database, and platform requirements. Your choice depends primarily on licensing needs and whether you require IBM DB2 and/or SQLite support.

Quick Selection Guide

Do you have a YndigoBlue subscription?

No → Use YndigoBlue.Velocity.Community (free, MySQL & PostgreSQL only, limited features)
Yes, and need DB2 or SQLite?
- No → Use YndigoBlue.Velocity (standard, works on all platforms)
- Yes → Use a platform-specific package:
  - YndigoBlue.Velocity.Windows (x64)
  - YndigoBlue.Velocity.Linux (x64)
  - YndigoBlue.Velocity.MacOS (Arm64)
  - YndigoBlue.Velocity.RaspberryPi (Arm64, SQLite only)

Package Comparison

Package	License	Platforms	Architecture	Databases	Geospatial	Full-Text	Schema Versioning	Multi-Schema
YndigoBlue.Velocity.Community	Free	All .NET 10	Any	MySQL, PostgreSQL only	❌	❌	❌	❌
YndigoBlue.Velocity	Subscription	All .NET 10	Any	All except DB2, SQLite	✅	✅	✅	✅
YndigoBlue.Velocity.Windows	Subscription	Windows	x64	All 7 databases	✅	✅	✅	✅
YndigoBlue.Velocity.Linux	Subscription	Linux	x64	All 7 databases	✅	✅	✅	✅
YndigoBlue.Velocity.MacOS	Subscription	macOS	Arm64	All 7 databases	✅	✅	✅	✅
YndigoBlue.Velocity.RaspberryPi	Subscription	Raspberry Pi OS	Arm64	All except DB2	✅	✅	✅	✅

All 7 Databases: IBM DB2, MySQL, Oracle, PostgreSQL, SQLite, SQL Server, Teradata

YndigoBlue.Velocity.Community (Free Edition)

The Community Edition is freely available on nuget.org without requiring a YndigoBlue subscription. It provides core Velocity functionality for MySQL and PostgreSQL with feature limitations.

Use this package if you:

Want to evaluate Velocity without a subscription
Only need MySQL and/or PostgreSQL support
Don't require geospatial features (Geometry/Geography types)
Don't require full-text indexing
Don't require schema versioning (UpdateSchema())
Don't require multi-schema support within a single database
Are building small to medium-sized applications with basic data access needs

Installation:

dotnet add package YndigoBlue.Velocity.Community

Platform Support:

Works on all platforms supported by .NET 10
No platform-specific builds required
Cross-platform compatible (Windows, Linux, macOS, any architecture)

Feature Limitations:

Feature	Community	Full Editions
MySQL Support	✅	✅
PostgreSQL Support	✅	✅
Oracle, SQL Server, Teradata	❌	✅
IBM DB2, SQLite	❌	✅ (platform-specific)
Geospatial Types (Geometry/Geography)	❌	✅
Spatial Indexes	❌	✅
Full-Text Indexes	❌	✅
Schema Versioning (`UpdateSchema`)	❌	✅
Multi-Schema Support	❌	✅
Declarative Schemas (XML/JSON/YAML)	✅	✅
Programmatic Schema Creation	✅	✅
Query Builder	✅	✅
Object Binding	✅	✅
CSV Import/Export	✅	✅
Transaction Management	✅	✅

Important Notes:

The Community Edition is ideal for learning, development, testing, and small production applications
To upgrade to full feature support or add more databases, switch to a subscription-based package
The Community Edition receives the same updates and bug fixes as subscription packages

Tip

Start with the Community Edition to learn Velocity. When you need enterprise database support, geospatial features, or schema versioning, upgrade to a subscription package with minimal code changes.

YndigoBlue.Velocity (Standard)

The standard package works on all platforms supported by .NET 10 without requiring platform-specific builds.

Use this package if you:

Do NOT need IBM DB2 or SQLite support
Want maximum platform portability
Prefer simpler build configurations
Are using MySQL, Oracle, PostgreSQL, SQL Server, or Teradata

Installation:

dotnet add package YndigoBlue.Velocity

Important limitations:

DB2 and SQLite .NET providers are not referenced
DB2 and SQLite-specific classes and enums are unavailable
Cannot connect to DB2 or SQLite databases

Warning

If you might need DB2 or SQLite support in the future, start with a platform-specific package. Switching packages later requires code changes if you've used any database-specific APIs.

Platform-Specific Packages

Platform-specific packages include DB2 and SQLite support but require targeting specific architectures and operating systems.

Architecture Requirements

x64 - Windows and Linux packages
Arm64 - macOS and Raspberry Pi packages

Package Details

YndigoBlue.Velocity.Windows

dotnet add package YndigoBlue.Velocity.Windows

Platform: Windows
Architecture: x64
Includes: DB2, SQLite, and all other database providers

Prerequisites:

IBM DB2 (Net.IBM.Data.Db2):

Visual C++ Redistributable: Microsoft Visual C++ 2013 Redistributable (x64) - Required
- Download from Microsoft Visual C++ 2013 Redistributable (x64)
- The IBM DB2 client libraries (db2app64.dll and related components) were compiled with Visual Studio 2013 and require the VS2013 runtime (msvcr120.dll, msvcp120.dll)
- Why VS2013? IBM's DB2 data provider uses native libraries compiled against the Visual Studio 2013 toolchain. While newer VS2015-2022 runtimes are backward compatible for some scenarios, DB2's native components specifically require the VS2013 runtime libraries to function correctly
- The DB2 native libraries are bundled with Velocity and placed in {YourApp}\clidriver\bin\ in your application's output directory
- While msvcr120.dll and msvcp120.dll are bundled in the clidriver\bin directory, the full Visual C++ 2013 Redistributable is still required for dependent system components
No Additional Configuration: All DB2 libraries and dependencies are automatically loaded from your application's output directory

SQLite with Geospatial Support:

Native Libraries: SpatiaLite (mod_spatialite.dll) and all dependent libraries (libgeos.dll, libproj_9_2.dll, libxml2.dll, etc.) are bundled with Velocity
Library Location: All libraries are placed in {YourApp}\runtimes\win-x64\native\ in your application's output directory
No Additional Configuration: All required native binaries are included and automatically loaded by .NET's runtime library loading mechanism

YndigoBlue.Velocity.Linux

dotnet add package YndigoBlue.Velocity.Linux

Platform: Linux
Architecture: x64
Includes: DB2, SQLite, and all other database providers

Prerequisites:

IBM DB2 (Net.IBM.Data.Db2-lnx):

Environment Variable: Set LD_LIBRARY_PATH to point to the DB2 libraries bundled with your application:
```
export LD_LIBRARY_PATH=/path/to/your/app/clidriver/lib:$LD_LIBRARY_PATH
```
- Replace /path/to/your/app with your application's output directory (e.g., /home/user/myapp/bin/Release/net10.0)
- The DB2 native libraries (libdb2.so and related components) are bundled with Velocity and placed in {YourApp}/clidriver/lib/ in your application's output directory
- All required dependencies (including libxml2) are bundled with the clidriver package
No System Dependencies Required: All DB2 libraries and dependencies are included with Velocity

SQLite with Geospatial Support:

Environment Variable: Set LD_LIBRARY_PATH to point to the SpatiaLite libraries bundled with your application:
```
export LD_LIBRARY_PATH=/path/to/your/app/runtimes/linux-x64/native:$LD_LIBRARY_PATH
```
- Replace /path/to/your/app with your application's output directory (e.g., /home/user/myapp/bin/Release/net10.0)
- The full path would be something like /home/user/myapp/bin/Release/net10.0/runtimes/linux-x64/native
Native Libraries: SpatiaLite (mod_spatialite.so) and all dependent libraries (libgeos.so, libproj.so, libxml2.so, etc.) are bundled with Velocity
Library Location: All libraries are placed in {YourApp}/runtimes/linux-x64/native/ in your application's output directory
No System Dependencies Required: All SpatiaLite libraries and dependencies are included with Velocity

YndigoBlue.Velocity.MacOS

dotnet add package YndigoBlue.Velocity.MacOS

Platform: macOS
Architecture: Arm64
Includes: DB2, SQLite, and all other database providers

Prerequisites:

IBM DB2 (Net.IBM.Data.Db2-osx):

Environment Variable: Set DYLD_LIBRARY_PATH to point to the DB2 libraries bundled with your application (add to ~/.zshrc or ~/.bash_profile):
```
export DYLD_LIBRARY_PATH=/path/to/your/app/clidriver/lib:$DYLD_LIBRARY_PATH
```
- Note: macOS uses DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH
- Replace /path/to/your/app with your application's output directory (e.g., /Users/username/myapp/bin/Release/net10.0)
- The DB2 native libraries (libdb2.dylib and related components) are bundled with Velocity and placed in {YourApp}/clidriver/lib/ in your application's output directory
- All required dependencies (including libxml2) are bundled with the clidriver package
Architecture Note: Ensure you're using the Arm64 version compatible with Apple Silicon (M1/M2/M3/M4 processors)
No System Dependencies Required: All DB2 libraries and dependencies are included with Velocity

SQLite with Geospatial Support:

Environment Variable: Set DYLD_LIBRARY_PATH to point to the SpatiaLite libraries bundled with your application:
```
export DYLD_LIBRARY_PATH=/path/to/your/app/runtimes/osx-arm64/native:$DYLD_LIBRARY_PATH
```
- Replace /path/to/your/app with your application's output directory (e.g., /Users/username/myapp/bin/Release/net10.0)
- The full path would be something like /Users/username/myapp/bin/Release/net10.0/runtimes/osx-arm64/native
Native Libraries: SpatiaLite (mod_spatialite.dylib) and all dependent libraries (libgeos.dylib, libproj.dylib, libxml2.dylib, etc.) are bundled with Velocity
Library Location: All libraries are placed in {YourApp}/runtimes/osx-arm64/native/ in your application's output directory
No System Dependencies Required: All SpatiaLite libraries and dependencies are included with Velocity

YndigoBlue.Velocity.RaspberryPi

dotnet add package YndigoBlue.Velocity.RaspberryPi

Platform: Raspberry Pi OS
Architecture: Arm64
Includes: SQLite and all other database providers
Note: DB2 is NOT supported on Raspberry Pi

Prerequisites:

SQLite with Geospatial Support:

Environment Variable: Set LD_LIBRARY_PATH to point to the SpatiaLite libraries bundled with your application:
```
export LD_LIBRARY_PATH=/path/to/your/app/runtimes/linux-arm64/native:$LD_LIBRARY_PATH
```
- Replace /path/to/your/app with your application's output directory (e.g., /home/pi/myapp/bin/Release/net10.0)
- The full path would be something like /home/pi/myapp/bin/Release/net10.0/runtimes/linux-arm64/native
- Add this to ~/.bashrc or ~/.profile to make it permanent
Native Libraries: SpatiaLite (mod_spatialite.so) and all dependent libraries (libgeos.so, libproj.so, libxml2.so, etc.) are bundled with Velocity
Library Location: All libraries are placed in {YourApp}/runtimes/linux-arm64/native/ in your application's output directory
No System Dependencies Required: All SpatiaLite libraries and dependencies are included with Velocity

Why Platform-Specific Packages?

Platform-specific packages exist due to native library dependencies that cannot be unified across platforms:

IBM DB2: IBM distributes separate native DB2 data providers for each OS and architecture rather than providing a single managed .NET provider. This means you cannot use one package across all platforms when DB2 support is required.

SQLite Geospatial Support: Velocity provides geospatial capabilities for SQLite through native binaries (leveraging SpatiaLite and related libraries). These native extensions must be compiled separately for each platform architecture, requiring platform-specific packages to bundle the correct binaries for Windows x64, Linux x64, macOS Arm64, and Raspberry Pi Arm64.

Configuring Platform Targets

When using platform-specific packages, you must set the correct platform target in your project configuration to avoid compilation warnings and ensure proper native library loading.

Required Platform Targets

Windows/Linux packages: x64
macOS/Raspberry Pi packages: Arm64

Setting Platform Target in .csproj

<PropertyGroup>
  <PlatformTarget>x64</PlatformTarget>
</PropertyGroup>

For Arm64:

<PropertyGroup>
  <PlatformTarget>ARM64</PlatformTarget>
</PropertyGroup>

See Microsoft's documentation on Specifying Target Platform for more details.

Multi-Platform Build Strategies

If you need to support multiple platforms with DB2 or SQLite, you'll need to create separate builds for each platform. Here are recommended approaches:

Approach 1: Conditional Package References

Use MSBuild conditions to reference different packages based on the target runtime:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'win-x64'">
    <PackageReference Include="YndigoBlue.Velocity.Windows" Version="2025.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-x64'">
    <PackageReference Include="YndigoBlue.Velocity.Linux" Version="2025.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'osx-arm64'">
    <PackageReference Include="YndigoBlue.Velocity.MacOS" Version="2025.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(RuntimeIdentifier)' == 'linux-arm64'">
    <PackageReference Include="YndigoBlue.Velocity.RaspberryPi" Version="2025.1.0" />
  </ItemGroup>
</Project>

Approach 2: Separate Project Files

Create separate .csproj files for each platform:

MyApp.Windows.csproj
MyApp.Linux.csproj
MyApp.MacOS.csproj

Each references the appropriate Velocity package and shares the same source files using Compile Include.

Approach 3: MSBuild Choose Element

Use the Choose Element for more complex conditional logic:

<Choose>
  <When Condition="'$(OS)' == 'Windows_NT'">
    <ItemGroup>
      <PackageReference Include="YndigoBlue.Velocity.Windows" Version="2025.1.0" />
    </ItemGroup>
    <PropertyGroup>
      <PlatformTarget>x64</PlatformTarget>
    </PropertyGroup>
  </When>
  <When Condition="'$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::Linux)))' == 'true'">
    <ItemGroup>
      <PackageReference Include="YndigoBlue.Velocity.Linux" Version="2025.1.0" />
    </ItemGroup>
    <PropertyGroup>
      <PlatformTarget>x64</PlatformTarget>
    </PropertyGroup>
  </When>
  <When Condition="'$([System.Runtime.InteropServices.RuntimeInformation]::IsOSPlatform($([System.Runtime.InteropServices.OSPlatform]::OSX)))' == 'true'">
    <ItemGroup>
      <PackageReference Include="YndigoBlue.Velocity.MacOS" Version="2025.1.0" />
    </ItemGroup>
    <PropertyGroup>
      <PlatformTarget>ARM64</PlatformTarget>
    </PropertyGroup>
  </When>
</Choose>

Building for Multiple Platforms

Use runtime identifiers (RIDs) when publishing:

# Windows
dotnet publish -r win-x64 -c Release

# Linux
dotnet publish -r linux-x64 -c Release

# macOS
dotnet publish -r osx-arm64 -c Release

# Raspberry Pi
dotnet publish -r linux-arm64 -c Release

Switching Between Packages

If you need to switch between Community, standard, and platform-specific packages:

Upgrading from Community to Full Edition

Uninstall the Community package:

dotnet remove package YndigoBlue.Velocity.Community

Configure the YndigoBlue NuGet feed with your subscription credentials (see Getting Started)

Install a full edition package:

# Standard package
dotnet add package YndigoBlue.Velocity

# Or platform-specific
dotnet add package YndigoBlue.Velocity.Windows

Update your project file to set the correct PlatformTarget (if using platform-specific packages)
Review your code for features that are now available:
- Geospatial data types and operations
- Full-text indexes
- Schema versioning with UpdateSchema()
- Multi-schema support
- Additional database connections (Oracle, SQL Server, Teradata, DB2, SQLite)
Test thoroughly to ensure all database operations work as expected

Switching Between Full Edition Packages

Uninstall the current package:

dotnet remove package YndigoBlue.Velocity

Install the new package:

dotnet add package YndigoBlue.Velocity.Windows

Update your project file to set the correct PlatformTarget
Review your code for any database-specific APIs that may now be available (or unavailable)
Test thoroughly to ensure all database operations work as expected

Table of Contents

Platform Selection

Quick Selection Guide

Package Comparison

YndigoBlue.Velocity.Community (Free Edition)

Tip

YndigoBlue.Velocity (Standard)

Warning

Platform-Specific Packages

Architecture Requirements

Package Details

YndigoBlue.Velocity.Windows

YndigoBlue.Velocity.Linux

YndigoBlue.Velocity.MacOS

YndigoBlue.Velocity.RaspberryPi

Why Platform-Specific Packages?

Configuring Platform Targets

Required Platform Targets

Setting Platform Target in .csproj

Multi-Platform Build Strategies

Approach 1: Conditional Package References

Approach 2: Separate Project Files

Approach 3: MSBuild Choose Element

Building for Multiple Platforms

Switching Between Packages

Upgrading from Community to Full Edition

Switching Between Full Edition Packages