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.

DevOps-Ready Database Management. Velocity is built for modern DevOps practices. Version-control your database schemas alongside application code using declarative XML, JSON, or YAML definitions. Integrate schema deployments into CI/CD pipelines with programmatic schema updates and migrations. Automate database provisioning across development, staging, and production environments using the same codebase—whether targeting PostgreSQL in development, SQL Server in staging, or Oracle in production. Velocity's schema introspection and comparison capabilities enable safe, automated database migrations without manual SQL scripts.

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—handling auto-incrementing columns, sequences, and identity fields automatically with the appropriate syntax for each vendor. 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, without having to understand the nuances of multiple different flavors of SQL. 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 and JSON schema validation
  • Programmatic schema creation that supports advanced features across all supported databases
  • Database introspection to reverse-engineer existing databases

Data Operations

  • Full DQL support with fluent query builder and parameterized queries
  • Comprehensive DML including INSERT, UPDATE, and DELETE operations
  • Batch operations for high-performance data import/export, with configurable options 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, GEOMETRY COLLECTION, and MULTI-X versions of these 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 using Velocity query support for portability across database vendors
  • 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
};
var usersTable = schema.GetTable("users");
var record = new Record<User>(usersTable, BindingType.SnakeCase);
record.Bind(user);
manager.AddRecord(record);

// Query with the fluent API
var query = new Query()
    .SelectAll(usersTable)
    .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:

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.