Create "Best Practices" / "Known Issues" Documentation

[caleblloyd]

Library users should be educated on the best way to implement the library and warned of any known issues that can cause bad performance in the driver. This should either be a Wiki page, in the README.md, or in some other .md file that is linked to from README.md

Best Practices

Use async methods all the way down

Known Issues

Calling DbConnection.Open in .NET Core can lead to thread pool lock-ups when processing hundreds of synchronous requests per second.

• Recommended Fix: use await DbConnection.OpenAsync from an async method
• If you must use the synchronous DbConnection.Open, warm the connection pool:
  1. Set min pool size in the connection string
  2. Call DbConnection.Open(); DbConnection.Close(); on application startup

[caleblloyd]

The Synchronous Best Practices can be simplified:

If using synchronous methods, ensure that your thread pool is at least the size of the number of concurrent connections you plan to support. For example, if you are creating a web server using synchronous methods that needs to support serving 500 Requests Per Second, set the minimum thread pool size to 500.

.NET Core Configuration example:

"runtimeOptions": {
  "configProperties": {
    "System.GC.Server": true,
    "System.GC.Concurrent": true,
    "System.Threading.ThreadPool.MinThreads": 500
  }
},

[caleblloyd]

@bgrainger what do you think about adding GitHub Pages to this project and putting official documentation there?

If you want to make me an editor on the project I can set the whole thing up. I will only maintain the gh-pages branch directly in this repo, everything else I'll still PR from my fork.

[bgrainger]

Sounds good. That might also be a good way of addressing the documentation changes I mentioned in #84: if the GitHub pages site contains more consumer-focused topics ("how to install", "how to report a bug", etc.) than the project README could reamin developer-focused ("how to build", "how to run tests") but should have a link to the user-facing site.