Table of Contents

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

YndigoBlue.Velocity.Linux

dotnet add package YndigoBlue.Velocity.Linux
  • Platform: Linux
  • Architecture: x64
  • Includes: DB2, SQLite, and all other database providers

YndigoBlue.Velocity.MacOS

dotnet add package YndigoBlue.Velocity.MacOS
  • Platform: macOS
  • Architecture: Arm64
  • Includes: DB2, SQLite, and all other database providers

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

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

  1. Uninstall the Community package:

    dotnet remove package YndigoBlue.Velocity.Community

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

  3. Install a full edition package:

    # Standard package
dotnet add package YndigoBlue.Velocity

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

  4. Update your project file to set the correct PlatformTarget (if using platform-specific packages)

  5. 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)

  6. Test thoroughly to ensure all database operations work as expected

Switching Between Full Edition Packages

  1. Uninstall the current package:

    dotnet remove package YndigoBlue.Velocity

  2. Install the new package:

    dotnet add package YndigoBlue.Velocity.Windows

  3. Update your project file to set the correct PlatformTarget

  4. Review your code for any database-specific APIs that may now be available (or unavailable)

  5. Test thoroughly to ensure all database operations work as expected