Quickstart

Thong Nguyen edited this page Jan 19, 2016 · 5 revisions

Intro

Shaolinq is designed to enable fast, feature rich and database agnostic access via Linq. In addition to being able to query using Linq, Shaolinq allows Linq based batch deletes as well as single-trip object updates.

Installing

Shaolinq is available as the following nuget packages:

Shaolinq - base package Shaolinq.Sqlite - required for Sqlite support Shaolinq.Postgres - required for Postgres support Shaolinq.MySql - required for MySql support Shaolinq.SqlServer - required for SqlServer support

Concepts

Data Object Model

To get as close to real SQL as possible with Linq queries Shoalinq does not hide the underlying SQL database schema. Unlike other ORMs (EntityFramework etc), Shaolinq DataAccessObjects and DataAccessModels are intentionally not POCOs. They are defined with using abstract C# classes and attributes and map one-to-one the underlying SQL DDL. POCO object models, if they exist, should be mapped to the underlying DataAccessModel and should be considered to exist at a layer above the Shaolinq model.

Linq queries

In order to allow easy testing and replacement of the underlying database, Shaolinq hides differences between different database engines and SQL dialects. All database queries (creates, updates, deletes) will be translated to the appropriate SQL. Shaolinq hides and emulates differences with the underlying engines. For example, when a database does not support deferred referential integrity checks, Shaolinq will shuffle the order in which objects/rows are persisted to satisfy integrity checks.

Defining your Data Access Model

A DataAccessModel defines the set of DataAccessObjects (database tables) that in your database. DataAccessObjects (tables) are defined by inheriting from the DataAccessObject class and DataAccessModels (databases) are defined by inheriting from the DataAccessModel class. For every DataAccessObject you define you should define a matching abstract readonly property on the DataAccessModel.

Properties (database columns) are declared on DataAccessObjects by creating an abstract read/write property decorated with the PersistedMember attribute.

[DataAccessObject]
public abstract class Person : DataAccessObject
{
    [PersistedMember]
    public abstract string Name { get; set; }
}

[DataAccessModel]
public abstract class ExampleModel : DataAccessModel
{
    [DataAccessObjects]
    public abstract DataAccessObjects<Person> People { get; }
}

Creating the Database

Shaolinq supports Sqlite, MySql, Postgres and MySql out of the box and adding new providers requires very little code -- especially if the RDBMS supports mostly standardised SQL. Providers can be configured within your app.config/web.config or alternatively directly code. Each provider provides helper methods for quickly creating configurations.

Creating an in-memory Sqlite database from the example model is easy:

using Shaolinq;
using Shaolinq.Sqlite;

var configuration = SqliteConfiguration.Create(":memory:");
var model = DataAccessModel.BuildDataAccessModel<ExampleModel>(configuration);

model.Create(DatabaseCreationOptions.DeleteExistingDatabase);

Creating an MySql database from the example model is just as easy:

using Shaolinq;
using Shaolinq.MySql;

var configuration = MySqlConfiguration.Create("ExampleDatabase", "localhost", "root", "root");
var model = DataAccessModel.BuildDataAccessModel<ExampleModel>(configuration);

model.Create(DatabaseCreationOptions.DeleteExistingDatabase);