Ways to instantiate PetaPoco

There are various way to construct a new instance of PetaPoco, each solving a particular use case.

The API, as it stands, comprises:

// Fluent configuration constructor
public Database(IBuildConfiguration configuration)

// Traditional constructors
public Database()
public Database(string connectionStringName)
public Database(IDbConnection connection, IMapper defaultMapper = null)
public Database(string connectionString, string providerName)
public Database(string connectionString, DbProviderFactory factory)
public Database(string connectionString, IProvider provider, IMapper defaultMapper = null)

General information

Version 5.1.84 or greater does not require a DbProviderFactory registration for any particular SQL client. However, there is potential for a minor gotcha here, as the provider name still needs to be set as PetaPoco uses this to choose correct DB provider. A list of valid provider names is given below.

Note: Users of the T4 templates will still require a DbProviderFactory registration, a valid .net provider name and the additional GAC registration of their selected SQL client. For more detailed instructions for the T4 template usage, please read the top of the T4 include file.

Fluent configuration constructor

public Database(IBuildConfiguration configuration)

PetaPoco supports fluent configuration and is the easiest way to configure and create PetaPoco instances. Please read the documentation for more information.

Traditional constructors

public Database()

The parameterless constructor is a quick and easy way to create a new instance of PetaPoco. This constructor will use the first connection string it finds in the app/web configuration.

Sample postgre app/web configuration file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="postgres" connectionString="Host=127.0.0.1;Username=petapoco;Password=petapoco;Database=petapoco;Port=5001;" providerName="Npgsql"/>
  </connectionStrings>
</configuration>

Note: If you have a machine.config file (as most developers' machines do), that file is read before app.config, so that this constructor may not give the results you expect. If you want your project to always ignore connection strings in machine.config and just use the ones in app.config, then add a <clear /> element in app.config before your first connection string:

<configuration>
  <connectionStrings>
    <clear />
    <add name=etc. />
  </connectionStrings>
</configuration>

---

public Database(string connectionStringName)

Hopefully this one is fairly obvious. If you guessed it maps the given connection string name to a connection string in the app/web config with the same name, then congrats for you.

Note: Ensure you give the connection string entry a valid provider name. A table of valid provider names can be found here. If no provider name is set, the default SQL Server provider is used.

Sample MySQL app/web configuration file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <connectionStrings>
        <add name="mysql" connectionString="Server=127.0.0.1;Uid=petapoco;Pwd=petapoco;Database=petapoco;Port=5002" providerName="MySql" />        
    </connectionStrings>
</configuration>

Sample instantiation of PetaPoco using the aforementioned MySQL configuration.

var db = new Database("mysql");

---

public Database(IDbConnection connection, IMapper defaultMapper = null)

The constructor which takes an instance of an existing connection is one of PetaPoco's more interesting and less known features. The why lies with the use case. It's not hard to imagine a situation where a project uses its own implementation of a DAL or a product like EF and has a need to easily access/manipulate data. In such a case, one can simply acquire a IDbConnection and construct an instance of PetaPoco for easy data access and manipulation.

Note: Please be aware that PetaPoco does not take ownership of the connection management when using this constructor, that responsibility to left to the caller.

---

public Database(string connectionString, string providerName)

With this constructor one simply provides a connection string and a provider name. A table of valid provider names can be found here.

---

public Database(string connectionString, DbProviderFactory factory)

---

public Database(string connectionString, IProvider provider, IMapper defaultMapper = null)

This constructor is the one of the more flexible when compared with the others. The flexibility is due to acceptance of a a provider and optional default mapper. The IProvider is the interface that all built-in DB providers inherit. This means that using this constructor, one can provide their own DB provider, perhaps supporting an unsupported DB type, or their own customised DB type by extending one of the built-in providers. Or simply, to have absolute control.

Sample instantiation of firebird DB.

var connectionString = ConfigurationManager.ConnectionStrings["firebird"].ConnectionString;
var db = new Database(connectionString, new FirebirdDBPovider());

Sample custom SQL Server DB Provider

public class CustomSqlServerDatabaseProvider : SqlServerDatabaseProvider
{
    public override string GetExistsSql()
    {
        return base.GetExistsSql() + "/*PetaWasEre2015/*";
    }
}

var connectionString = ConfigurationManager.ConnectionStrings[0].ConnectionString;
var db = new Database(connectionString, new CustomSqlServerDatabaseProvider());