linq2db

# LINQ to DB

[![Discord](https://img.shields.io/discord/1089930409577545948?label=discord)](https://discord.gg/PcV6pTXt4s) [![NuGet Version](https://img.shields.io/nuget/vpre/linq2db)](https://www.nuget.org/profiles/LinqToDB) [![License](https://img.shields.io/github/license/linq2db/linq2db)](https://github.com/linq2db/linq2db/blob/master/MIT-LICENSE.txt)
 [!["good first issue" tasks](https://img.shields.io/github/issues/linq2db/linq2db/good%20first%20issue.svg)](https://github.com/linq2db/linq2db/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)

[![Master branch build](https://img.shields.io/azure-devops/build/linq2db/linq2db/5/master?label=build%20(master))](https://dev.azure.com/linq2db/linq2db/_build?definitionId=5&_a=summary) [![Latest build](https://img.shields.io/azure-devops/build/linq2db/linq2db/5?label=build%20(latest))](https://dev.azure.com/linq2db/linq2db/_build?definitionId=5&_a=summary)

LINQ to DB is the fastest LINQ database access library offering a simple, light, fast, and type-safe layer between your POCOs and your database.

Architecturally it is one step above micro-ORMs like Dapper, Massive, or PetaPoco, in that you work with LINQ expressions, not with magic strings, while maintaining a thin abstraction layer between your code and the database. Your queries are checked by the C# compiler and allow for easy refactoring.

However, it's not as heavy as LINQ to SQL or Entity Framework. There is no change-tracking, so you have to manage that yourself, but on the positive side you get more control and faster access to your data.

In other words **LINQ to DB is type-safe SQL**.

**LINQ to DB** also very nice for F# developers (see Tests/FSharp and Source/LinqToDB.FSharp project for details).

Development version nugets [feeds](https://dev.azure.com/linq2db/linq2db/_artifacts/feed/linq2db) ([how to use](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio#package-sources))

## Standout Features

- Rich Querying API:
  - [Explicit Join Syntax](https://linq2db.github.io/articles/sql/Join-Operators.html) (In addition to standard LINQ join syntax)
  - [CTE Support](https://linq2db.github.io/articles/sql/CTE.html)
  - [Bulk Copy/Insert](https://linq2db.github.io/articles/sql/Bulk-Copy.html)
  - [Window/Analytic Functions](https://linq2db.github.io/articles/sql/Window-Functions-%28Analytic-Functions%29.html)
  - [Merge API](https://linq2db.github.io/articles/sql/merge/Merge-API-Description.html)
- Extensibility:
  - [Ability to Map Custom SQL to Static Functions](https://github.com/linq2db/linq2db/tree/master/Source/LinqToDB/Sql/)

See [Github.io documentation](https://linq2db.github.io/index.html) for more details.

<!-- You can visit our [blog](http://blog.linq2db.com/) -->

Code examples and demos can be found [here](https://github.com/linq2db/examples) or in [tests](https://github.com/linq2db/linq2db/tree/master/Tests/Linq).

[Release notes](https://github.com/linq2db/linq2db/wiki/Releases-and-Roadmap) page.

### Related Linq To DB and 3rd-party projects

- [linq2db.EntityFrameworkCore](https://github.com/linq2db/linq2db/tree/master/Source/LinqToDB.EntityFrameworkCore) (adds support for linq2db functionality in EF.Core projects)
- [LinqToDB.Identity](https://github.com/linq2db/LinqToDB.Identity) - ASP.NET Core Identity provider using Linq To DB
- [LINQPad Driver](https://github.com/linq2db/linq2db/tree/master/Source/LinqToDB.LINQPad)
- [DB2 iSeries Provider](https://github.com/LinqToDB4iSeries/Linq2DB4iSeries)
- [ASP.NET Core Template](https://github.com/David-Mawer/LINQ2DB-MVC-Core-5)
- [PostGIS extensions for linq2db](https://github.com/apdevelop/linq2db-postgis-extensions)

Notable open-source users:

- [nopCommerce](https://github.com/nopSolutions/nopCommerce) - popular open-source e-commerce solution
- [OdataToEntity](https://github.com/voronov-maxim/OdataToEntity) - library to create OData service from database context
- [SunEngine](https://github.com/sunengine/SunEngine) - site, blog and forum engine

Unmantained projects:

- [IdentityServer4.LinqToDB](https://github.com/linq2db/IdentityServer4.LinqToDB) - IdentityServer4 persistence layer using Linq To DB

## Configuring connection strings

### Passing Into Constructor

You can simply pass connection string into `DataConnection` or `DataContext` constructor using [`DataOptions`](https://linq2db.github.io/api/LinqToDB.DataOptions.html) class.

Minimal configuration example:

```cs
var db = new DataConnection(
  new DataOptions()
    .UseSqlServer(@"Server=.\;Database=Northwind;Trusted_Connection=True;"));
```

Use connection configuration action to setup SqlClient-specific authentication token:

```cs
var options = new DataOptions()
  .UseSqlServer(connectionString, SqlServerVersion.v2017, SqlServerProvider.MicrosoftDataSqlClient)
  .UseBeforeConnectionOpened(cn =>
    {
        ((SqlConnection)cn).AccessToken = accessToken;
    });

// pass configured options to data context constructor
var dc = new DataContext(options);
```

> [!TIP]
> There are a lot of configuration methods on `DataOptions` you can use.

> [!TIP]
> It is recommended to create configured `DataOptions` instance once and use it everywhere. E.g. you can register it in your DI container.

### Using Config File (.NET Framework)

In your `web.config` or `app.config` make sure you have a connection string (check [this file](https://github.com/linq2db/linq2db/blob/master/Source/LinqToDB/ProviderName.cs) for supported providers):

```xml
<connectionStrings>
  <add name="Northwind" 
    connectionString = "Server=.\;Database=Northwind;Trusted_Connection=True;" 
    providerName     = "SqlServer" />
</connectionStrings>
```

### Using Connection String Settings Provider

Alternatively, you can implement custom settings provider with `ILinqToDBSettings` interface, for example:

```cs
public class ConnectionStringSettings : IConnectionStringSettings
{
    public string ConnectionString { get; set; }
    public string Name             { get; set; }
    public string ProviderName     { get; set; }
    public bool   IsGlobal         => false;
}

public class MySettings : ILinqToDBSettings
{
    public IEnumerable<IDataProviderSettings> DataProviders
        => Enumerable.Empty<IDataProviderSettings>();

    public string DefaultConfiguration => "SqlServer";
    public string DefaultDataProvider  => "SqlServer";

    public IEnumerable<IConnectionStringSettings> ConnectionStrings
    {
        get
        {
            // note that you can return multiple ConnectionStringSettings instances here
            yield return
                new ConnectionStringSettings
                {
                    Name             = "Northwind",
                    ProviderName     = ProviderName.SqlServer,
                    ConnectionString =
                        @"Server=.\;Database=Northwind;Trusted_Connection=True;"
                };
        }
    }
}
```

And later just set on program startup before the first query is done (Startup.cs for example):

```cs
DataConnection.DefaultSettings = new MySettings();
```

### Use with ASP.NET Core and Dependency Injection

See [article](https://linq2db.github.io/articles/get-started/asp-dotnet-core/index.html).

## Define **POCO** class

You can generate POCO classes from your database using [linq2db.cli](https://www.nuget.org/packages/linq2db.cli)  `dotnet tool`.

Alternatively, you can write them manually and map to database using mapping attributes or `fluent mapping configuration`. Also you can use POCO classes as-is without additional mappings if they use same naming for classes and properties as table and column names in database.

### Configuration using mapping attributes

```c#
using System;
using LinqToDB.Mapping;

[Table("Products")]
public class Product
{
  [PrimaryKey, Identity]
  public int ProductID { get; set; }

  [Column("ProductName"), NotNull]
  public string Name { get; set; }

  [Column]
  public int VendorID { get; set; }

  [Association(ThisKey = nameof(VendorID), OtherKey=nameof(Vendor.ID))]
  public Vendor Vendor { get; set; }

  // ... other columns ...
}
```

This approach involves attributes on all properties that should be mapped. This way lets you to configure all possible things linq2db ever supports. There is one thing to mention: if you add at least one attribute into POCO, all other properties should also have attributes, otherwise they will be ignored:

```c#
using System;
using LinqToDB.Mapping;

[Table("Products")]
public class Product
{
  [PrimaryKey, Identity]
  public int ProductID { get; set; }

  // Property `Name` will be ignored as it lacks `Column` attibute.
  public string Name { get; set; }
}
```

### Fluent Configuration

This method lets you configure your mapping dynamically at runtime. Furthermore, it lets you to have several different configurations if you need so. You will get all configuration abilities available with attribute configuration. These two approaches are interchangeable in their abilities. This kind of configuration is done through the class `MappingSchema`.

With Fluent approach you can configure only things that require it explicitly. All other properties will be inferred by linq2db:

```c#
// IMPORTANT: configure mapping schema instance only once
// and use it with all your connections that need those mappings
// Never create new mapping schema for each connection as
// it will seriously harm performance
var myFluentMappings = new MappingSchema();
var builder       = new FluentMappingBuilder(mappingSchema);

builder.Entity<Product>()
    .HasTableName("Products")
    .HasSchemaName("dbo")
    .HasIdentity(x => x.ProductID)
    .HasPrimaryKey(x => x.ProductID)
    .Ignore(x => x.SomeNonDbProperty)
    .Property(x => x.TimeStamp)
        .HasSkipOnInsert()
        .HasSkipOnUpdate()
    .Association(x => x.Vendor, x => x.VendorID, x => x.VendorID, canBeNull: false)
    ;

//... other mapping configurations

// commit configured mapp