Venflow

A brand new, fast and lightweight ORM, build for PostgreSQL.

Description

Venflow is a brand new ORM, written from the ground up to try and provide an alternative to EF-Core and many other ORMs. It allows you to define Models and their relations with each other. Additionally it maps all queries on its own while still maintaining great performance.

Programming language: C#

License: Apache License 2.0

Tags: ORM     SQL     PostgreSQL    

README

Venflow A brand new, fast, and lightweight ORM. | Documentation

About

Venflow is a brand new ORM, written from the ground up to try and provide an alternative to EF-Core and many other ORMs. It allows you to define Models and their relations with each other. Additionally it maps all queries on its own while still maintaining great performance, with options for custom SQL.

Lets face it, EF-Core is awesome, but it can be slow, really slow. However this library tries to overcome that by providing similar features while maintaining great performance. Venflow comes with a very similar UX to Dapper and EF-Core, in order to keep the learning curve as low as possible.

Features

• Simple change-tracking for update operations
• Autogenerated Inserts
• Autogenerated Deletes
• Autogenerated Query Materializer, Join Generator
• SQL Injection safe string Interpolated SQL

Collaboration

If you want to collaborate on this project more, than creating issues and PR's, feel free to contact me on any of the mentioned contacts at the bottom of the file.

How you can help other than that? This can be done in numerous ways, over on the issue section, such as:

• Creating feature requests
• Creating pull requests
• Reporting bugs

Installation

The beta versions of Venflow can currently be downloaded on nuget.org. However please do note that since this package is still in beta, it may still contain bugs and other issues.

Also you can install it via the Package Manager Console:

Install-Package Venflow

Comparison

Benchmarking ORM's isn't an easy task, since there are a bunch of different factors which can alter the result in one way or another. I do not show any beautiful graphs here for the simple reason, that showing them would be pretty impractical, since there would be just too many. That is also the reason why I tried to come up with a composite number based on the benchmark results. If you still want check all the individual benchmarks, which you definitely should, the source code can be found [here](./src/Venflow/Venflow.Benchmarks) and the results as .csv and .md are over [here](./benchmarks).

Lets just directly hop into the composite numbers of each tested ORM.

ORM Name	Composite Score*	Mean Score*	Allocation Score*
#1 Venflow	9.204	8.463	0.741
#2 Dapper**	16.794	13.076	3.718
#3 RepoDb**	49.494	43.254	6.240
#4 EFCore	245.869	195.152	50.717

* Lower is considered to be better ** Do have missing benchmark entries for specific benchmark groups and therefor either might have better/worse scores.

Now how do I calculate this magic number? The formula is as following:

compositeScore = Σ((meanTime / lowestMeanTimeOfGroup - 1) + (allocation / lowestAllocationOfGroup - 1) / 10)

A group is considered as a list of benchmark entries which are inside the same file and have the same *count and target framework. Now as some ORM's don't have any benchmarks entries for specific benchmark groups it will take instead take the lowest mean and the lowest allocation from this group. The source code of the calculation can be found [here](./src/Venflow/Venflow.Score).

Disclaimer

The benchmarks themselves or even the calculation of the composite numbers may not be right and contain bugs. Therefor consider these results with a grain of salt. If you find any bugs inside the calculations or in the benchmarks please create an issue and I'll try to fix it ASAP.

Is this package for you?

This package is more a competitor to Dapper than EF-Core since it supports Linq2Sql, Database first, and migrations, which neither Dapper or Venflow support out of the box. On the other hand you need to consider the Database you will end up using, if you aren't using PostgreSQL you will have to use a different ORM, at least at this state of the project.

But why should I use Venflow over Dapper anyway?

Venflow supports a lot more things out of the box, such as automatically generated Delete/Insert statements, as well as simple change tracking to easily update specific entities. Another big factor, which probably is one of the biggest differences to Dapper, are the automatically generated materializers for queries. A lot of the times a materializer generated by Venflow will always be faster, especially for bigger tables, than a hand written Dapper one. This is due to the nature of how Dapper and Venflow handle the parsing of SQL results.

Basic usage

As already mentioned, Venflow tries to keep the learning curve from other ORM's as low as possible, therefor a lot of patterns will seem familiar from either EFCore or Dapper.

Basic configuration

The official documentation and guides can be found here

In Venflow you are reflecting your PostgreSQL database with the Database class, which will host all of your tables. This class represents a connection to your database and therefor doesn't support multi threaded use. In the following example we will configure a database containing two tables, Blogs and Posts. One Blog contains many posts and a post contains a single Blog.

public class BlogDatabase : Database
{
    public Table<Blog> Blogs { get; set; }
    public Table<Post> Posts { get; set; }

    public BlogDatabase() : base("Your connection string.")
    {
    }
}

Now lets configure the actual relation between Blogs and Posts through the EntityConfiguration<T> class. In the Configure , method you can configure several things such as the name of the table this entity should map to and much more. These configuration classes do automatically get discovered, if they are in the same assembly as the Database class. If they are not in the same assembly, you can override the Configure method in the Database class which passes in a DatabaseOptionsBuilder, which will allow you to specify assemblies which should also be searched for entity configurations.

public class BlogConfiguration : EntityConfiguration<Blog>
{
    protected override void Configure(IEntityBuilder<Blog> entityBuilder)
    {
        entityBuilder.HasMany(b => b.Posts)
                     .WithOne(p => p.Blog)
                     .UsingForeignKey(p => p.PostId);
    }
}

A instance of your Database class exposes the underlying connection and the actual CRUD builders. In the example below you can see how you would query a set of Blogs with their posts.

await using var database = new BlogDatabase(); // You should register a Transient/Scoped your DI Container.

const string sql = @"SELECT * FROM ""Blogs"" JOIN ""Posts"" ON ""Posts"".""BlogId"" = ""Blogs"".""Id""";

// You can re-use this in different BlogDatabase instances through the database.Blogs.QueryAsync() method
// If you intend to reuse the query below you need to pass the QueryBatch method false for the disposeCommand,
// otherwise the underyling command will be disposed after the first use.
var blogs = database.Blogs.QueryBatch(sql).JoinWith(x => x.Posts).QueryAsync();

Subsequent joins can be configured using the ThenWith method. Do note, that one handy feature of Venflow is string interpolated SQL. This means that most of the methods which accept SQL also have a sibling named *Interpolated* which will automatically extract the used variables and use a parameterized query instead.

Road map

• Composed PK support
• Direct support for many to many relations
• Support for materialized Views
• Bulk operation support from PostgreSQL.Bulk
• Code-First
• AOT proxy/entity generation with Source Generators

Acknowledgements

I also want to mention all the other great packages out there, build by awesome people, which helped with building Venflow in one way or another such as being open-source.

• Npgsql by the Npgsql core contributers for providing an awesome and fast PostgreSQL data provider.
• Sharplab by ashmind and the sharplab.io website for immensely simplify the generation for IL.
• EF-Core by Microsoft and the .Net team for providing the inspiration for such an awesome surface API.
• RepoDb by mikependon for providing the idea of generating runtime IL/Expressions to boost performance.
• Fody by the Fody core contributers for providing an easy way to IL weave Venflow.
• GitHub for hosting the documentation with GitHub Pages and the repository itself.
• DocFX by Microsoft and the .Net team for providing a great any easy static markdown/documentation html generator.
• Typora for being a fully extensive and great markdown editor.
• GitKraken for providing a full fledged git UI with a bunch of great features.
• Shields for providing awesome badges for the README.

Awesome people which helped in the development

• LunarLite for helping me with highly complex logically issues.
• AnotherZane for being one of the early preview testers.
• Jas and Fatal for providing general surface API ideas.

Notes

Contact information

If you feel like something is not working as intended or you are experiencing issues, feel free to create an issue. Also for feature requests just create an issue. For further information feel free to send me an email at [email protected] or message me on Discord 24_minutes#7496.

Sponsors

I wanna thank JetBrains for providing me and the project with a free Open Source license for their whole JetBrains suite. Their tools greatly improve the development speed of this project. If you want to get a free Open Source license for your own project and their collaborators, visit their Open Source page.