Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jchristn/watsonorm
WatsonORM is a lightweight and easy to use object-relational mapper (ORM) in C# for .NET Core.
https://github.com/jchristn/watsonorm
dotnet mysql mysql-database orm postgres postgresql postgresql-database repository-pattern sqlite sqlserver
Last synced: 1 day ago
JSON representation
WatsonORM is a lightweight and easy to use object-relational mapper (ORM) in C# for .NET Core.
- Host: GitHub
- URL: https://github.com/jchristn/watsonorm
- Owner: jchristn
- License: mit
- Created: 2020-05-09T19:37:37.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-19T18:29:46.000Z (3 months ago)
- Last Synced: 2024-12-19T08:07:21.816Z (9 days ago)
- Topics: dotnet, mysql, mysql-database, orm, postgres, postgresql, postgresql-database, repository-pattern, sqlite, sqlserver
- Language: C#
- Homepage:
- Size: 1.16 MB
- Stars: 22
- Watchers: 5
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# WatsonORM
| Library | Version | Downloads |
|---|---|---|
| WatsonORM (all supported database types) | [](https://www.nuget.org/packages/WatsonORM/) | [](https://www.nuget.org/packages/WatsonORM) |
| WatsonORM.Mysql | [](https://www.nuget.org/packages/WatsonORM.Mysql/) | [](https://www.nuget.org/packages/WatsonORM.Mysql) |
| WatsonORM.Postgresql | [](https://www.nuget.org/packages/WatsonORM.Postgresql/) | [](https://www.nuget.org/packages/WatsonORM.Postgresql) |
| WatsonORM.Sqlite | [](https://www.nuget.org/packages/WatsonORM.Sqlite/) | [](https://www.nuget.org/packages/WatsonORM.Sqlite) |
| WatsonORM.SqlServer | [](https://www.nuget.org/packages/WatsonORM.SqlServer/) | [](https://www.nuget.org/packages/WatsonORM.SqlServer) |
| WatsonORM.Core | [](https://www.nuget.org/packages/WatsonORM.Core/) | [](https://www.nuget.org/packages/WatsonORM.Core) |
## Description
WatsonORM is a lightweight and easy to use object-relational mapper (ORM) in C# for .NET Core built on top of DatabaseWrapper. WatsonORM supports Microsoft SQL Server, Mysql, MariaDB, PostgreSQL, and Sqlite databases, both on-premises and in the cloud.
Core features:
- Annotate classes and automatically create database tables
- Quickly create, read, update, or delete database records using your own objects
- Reduce time-to-production and time spent building scaffolding code
- Programmatic table creation and removal
For a sample app exercising this library, refer to the ```Test``` project contained within the solution.
## New in v3.0.x
- Dependency update
- Minor breaking changes
- Async API support
- Better support for updating multiple records
## Special Thanks
We'd like to give special thanks to those who have contributed or helped make the library better!
@Maclay74 @flo2000ace @MacKey-255
## Simple Example
This example uses ```Sqlite```. For ```SqlServer```, ```Mysql```, or ```Postgresql```, you must make sure the database exists. Tables will be automatically created in this example. Refer to the ```Test``` project for a complete example.
```csharp
using ExpressionTree;
using DatabaseWrapper.Core;
using Watson.ORM;
using Watson.ORM.Core;
// Apply attributes to your class
[Table("person")]
public class Person
{
[Column("id", true, DataTypes.Int, false)]
public int Id { get; set; }
[Column("firstname", false, DataTypes.Nvarchar, 64, false)]
public string FirstName { get; set; }
// Parameter-less constructor is required
public Person()
{
}
}
// Initialize
DatabaseSettings settings = new DatabaseSettings("./WatsonORM.db");
WatsonORM orm = new WatsonORM(settings);
orm.InitializeDatabase();
orm.InitializeTable(typeof(Person)); // initialize one table
orm.InitializeTables(new List { typeof(Person) }); // initialize multiple tables
// Insert
Person person = new Person { FirstName = "Joel" };
Person inserted = orm.Insert(person);
// Select
Person selected = orm.SelectByPrimaryKey(1);
// Select all records
List people = orm.SelectMany();
// Select many by column name
Expr e1 = new Expr("id", OperatorEnum.GreaterThan, 0);
people = orm.SelectMany(e1);
// Select many by property
Expr e2 = new Expr(
orm.GetColumnName(nameof(Person.Id)),
DbOperators.GreaterThan,
0);
people = orm.SelectMany(e2);
// Select many by property with pagination
// Retrieve 50 records starting at record number 10
people = orm.SelectMany(10, 50, e2);
// Select many with descending order
ResultOrder[] resultOrder = new ResultOrder[1];
resultOrder[0] = new ResultOrder("id", OrderDirectionEnum.Descending);
people = orm.SelectMany(null, null, e2, resultOrder);
// Update
inserted.FirstName = "Jason";
Person updated = orm.Update(inserted);
// Delete
orm.Delete(updated);
```
## Column Naming
Columns can be named *explicitly* by specifying the colum name in the ```Column``` attribute constructor. Alternatively, constructors that don't include a name can be used, in which case the name of the property will be used as the column name.
Example with explicit naming:
```csharp
[Column("id", true, DataTypes.Int, false)] // column name "id"
public int Id { get; set; }
[Column("firstname", false, DataTypes.Nvarchar, 64, false)] // column name "firstname"
public string FirstName { get; set; }
```
Example without explicit naming:
```csharp
[Column(true, DataTypes.Int, false)] // column name "Id"
public int Id { get; set; }
[Column(DataTypes.Nvarchar, 64, false)] // column name "FirstName"
public string FirstName { get; set; }
```
## Pagination with SelectMany
```SelectMany``` can be paginated by using the method with either signature ```(int? indexStart, int? maxResults, Expr expr)``` or ```(int? indexStart, int? maxResults, Expr expr, ResultOrder[] resultOrder)```. ```indexStart``` is the number of records to skip, and ```maxResults``` is the number of records to retrieve.
Paginated results are always ordered by the primary key column value in ascending order, i.e. ```ORDER BY id ASC``` in the ```Person``` example above.
## Validating One or More Tables
If you wish to determine if there are any errors or warnings associated with a given ```Type```, use either the ```ValidateTable``` or ```ValidateTables``` API:
```csharp
List errors = new List();
List warnings = new List();
// validate a single table
bool success = orm.ValidateTable(typeof(Person), out errors, out warnings);
// validate multiple tables
bool success = orm.ValidateTables(new List
{
typeof(Person),
typeof(Order),
typeof(Inventory)
},
out errors,
out warnings);
if (errors.Count > 0)
foreach (string error in errors) Console.WriteLine(error);
if (warnings.Count > 0)
foreach (string warning in warnings) Console.WriteLine(warning);
```
## Using Sqlite
Sqlite may not work out of the box with .NET Framework. In order to use Sqlite with .NET Framework, you'll need to manually copy the ```runtimes``` folder into your project output directory. This directory is automatically created when building for .NET Core. To get this folder, build the Test.Sqlite project and navigate to the ```bin/[debug||release]/[netcoreapp*||net5.0||net6.0]``` directory. Then copy the runtimes folder into the project output directory of your .NET Framework application.
## Using SQL Server
In order to use pagination with SQL Server, the ```SelectMany``` method containing the ```ResultOrder[] resultOrder``` parameter must be used.
## Using MySQL
While the ```DateTimeOffset``` type can be used in objects, with MySQL the offset is not persisted. It is recommended that you store UTC timestamps using the ```DateTime``` type instead.
## Using MariaDB
Use the MySQL constructor. MySQL constraints apply.
## Version history
Refer to CHANGELOG.md.