Before you Begin
Velocity is excellent for building data layers in enterprise applications, but it's not universally suited for every use case. This guide highlights scenarios where you should consider alternative tools.
As a replacement for SQL
Velocity is not a SQL replacement. The framework doesn't attempt to replicate SQL's flexibility or every possible query pattern. While the Manager class provides a RunSql() method for edge cases, it should be used sparingly. If your use case requires frequent raw SQL queries, Velocity probably isn't the best fit.
Additionally, Velocity prioritizes cross-platform compatibility and simplicity over comprehensive SQL support. Complex join patterns and uncommon SQL syntax are unlikely to be supported, and we don't plan to add them.
For reverse-engineering complex existing schemas
Velocity includes a LoadSchema() method to import existing database schemas, and it works well if the schema maps to supported data types. However, if you're locked into a single database vendor's specific design patterns, Velocity may not be ideal.
Velocity works best with a schema-first approach: define your schema declaratively in Velocity, apply it to your database, then work with the framework. Attempting to retrofit complex existing schemas often leads to friction.
When using unsupported data types
If you need a data type that Velocity doesn't support, you'll need to look elsewhere. Check the supported data types for each vendor before committing to Velocity. We're expanding type support over time, but your specific needs may not align with our roadmap.
The section on native types lays out our approach to the less common data types and how to handle them.
For vendor-specific database features
Velocity is designed around cross-platform compatibility. Vendor-specific features (Oracle partitioning, SQL Server temporal tables, PostgreSQL extensions, etc.) are rarely added to the framework. Occasionally we support them as context settings, but this is the exception, not the rule.
When maximum performance is critical
Velocity prioritizes cross-platform compatibility over raw performance. We optimize operations where possible, but we won't sacrifice platform portability or API clarity for marginal speed gains. If you find yourself writing vendor-detection code to optimize for specific databases, Velocity isn't the right tool.
For vendor-dependent implementations
If your data layer needs to make fundamentally different choices based on the database vendor—using different SQL patterns, avoiding features on some platforms, or customizing business logic per database—Velocity won't work well. Velocity is built for truly cross-platform data layers, not single-vendor-optimized ones.
When behavior differs from documentation
If the documentation doesn't mention a feature, it's not supported—by design. We don't compare Velocity against raw SQL capabilities or claim to replicate them. Our goal is cross-platform support first, and the documentation reflects what we actually support.