Introduction

Modern enterprise applications often need to support multiple database systems—whether for client flexibility, cloud migration strategies, or multi-tenancy requirements. However, each database vendor has unique SQL dialects, feature sets, and quirks that force developers to maintain separate code paths or settle for lowest-common-denominator solutions.

Velocity solves this problem. The YndigoBlue Velocity Framework enables developers to build a single, vendor-independent .NET data layer that works seamlessly across seven major relational database systems. Rather than abstracting away database capabilities like traditional ORMs, Velocity provides full access to advanced features through a unified API that works consistently across all supported databases.

Why Velocity?

Write Once, Run Anywhere Define your schema once in XML, JSON, or YAML, and Velocity generates the correct DDL for any supported database—from MySQL's AUTO_INCREMENT to Oracle's SEQUENCES to SQL Server's IDENTITY columns. Your application code remains unchanged regardless of which database your customer prefers.

Beyond Basic CRUD Velocity isn't just another ORM. It provides comprehensive database functionality including:

  • Geospatial data types and spatial indexes
  • Full-text indexing and search capabilities
  • Advanced constraint management (foreign keys, unique constraints, check constraints)
  • Transaction management with proper isolation
  • Batch import/export with CSV support
  • Over 70 database functions with consistent naming

Declarative and Programmatic Use declarative schema files for version-controlled database definitions, or build schemas programmatically in code. Query data using the fluent Query API or work directly with SQL when needed. Velocity gives you options without forcing a single approach.

Type-Safe Data Binding Work with strongly-typed C# objects using automatic data binding with configurable naming conventions (snake_case, camelCase). No more manually mapping between database records and domain objects.

Core Capabilities

Schema Management

  • 18 universal data types that map correctly to each database's native types
  • Multi-schema support with schema versioning and migration tracking
  • Declarative definitions in XML, JSON, or YAML with XSD validation
  • Programmatic schema creation using the fluent Schema API
  • Database introspection to reverse-engineer existing databases

Data Operations

  • Full DQL support with fluent query builder and parameterized queries
  • Comprehensive DML including INSERT, UPDATE, DELETE, and MERGE operations
  • Batch operations for high-performance data import/export
  • CSV import/export with configurable delimiters and type mapping
  • Transaction management with configurable isolation levels
  • Object binding for automatic mapping between C# objects and database records

Advanced Features

  • Geospatial support for POINT, LINESTRING, POLYGON, and GEOMETRY types
  • Spatial indexing for high-performance geographic queries
  • Full-text indexes with database-appropriate implementations
  • Constraints including primary keys, foreign keys, unique, check, and default values
  • Database views with automatic dependency resolution
  • Connection pooling and retry logic for production resilience

Developer Experience

  • IntelliSense support with comprehensive XML documentation
  • Type safety throughout the API surface
  • Fluent APIs for readable, discoverable code
  • Detailed logging with log4net integration
  • Clear error messages with actionable guidance

Quick Example

Here's how simple it is to work with Velocity:

using YndigoBlue.Velocity;
using YndigoBlue.Velocity.Connections;

// Connect to any supported database
using var connection = new PostgreSqlDatasourceConnection(
    hostname: "localhost",
    port: 5432,
    database: "myapp",
    username: "admin",
    password: "password"
);

using var manager = new Manager(connection);

// Load a declarative schema and build it
var schema = manager.ReadSchemaFromFile("schema.xml");
manager.BuildSchema(schema);

// Insert data using object binding
var user = new User {
    Name = "John Doe",
    Email = "john@example.com",
    CreatedAt = DateTime.UtcNow
};
manager.AddRecord(Record<User>.Bind(user));

// Query with the fluent API
var query = new Query("users")
    .Where("email", Comparison.Equal, "john@example.com")
    .OrderBy("created_at", Order.Descending);

var results = manager.Retrieve(query);
var users = Record<User>.BindResults(results);

Switch from PostgreSQL to SQL Server, Oracle, or any supported database by simply changing the connection type—no other code changes required.

Supported Databases

Velocity provides first-class support for seven major relational database systems:

  • IBM DB2 LUW - Enterprise-grade with multi-schema support
  • MySQL - Popular open-source with full InnoDB features
  • Oracle Database - Enterprise features including partitioning and sequences
  • PostgreSQL - Advanced open-source with excellent geospatial support
  • SQLite - Embedded database with folder-based schema support
  • Microsoft SQL Server - Enterprise database with spatial and full-text indexing
  • Teradata Vantage - Analytics platform with advanced query capabilities

All databases support the vast majority of Velocity capabilities, with database-specific optimizations applied automatically. See Datasource Limitations for the few feature restrictions that exist.

Platform Support

Velocity is built on .NET 10 and runs on any platform supported by the framework:

  • Windows (x64) - Full database support including DB2 and SQLite with SpatiaLite
  • Linux (x64) - Full database support including DB2 and SQLite with SpatiaLite
  • macOS (Arm64) - Full database support including DB2 and SQLite with SpatiaLite
  • Raspberry Pi (Arm64) - All databases except DB2, includes SQLite with SpatiaLite

Platform-specific packages handle database driver dependencies automatically. See Platform Selection for guidance on choosing the right package for your deployment scenario.

Getting Started

Ready to build database-agnostic applications? Head over to the Getting Started guide to:

  1. Set up your development environment
  2. Install the appropriate Velocity package
  3. Create your first schema
  4. Connect to your database
  5. Start querying and manipulating data

For a deeper dive into schema design, see Velocity Schemas.