GOTCHA!

You have entered the forest of goblins! A collection of gotchas goblins to look out for when using the driver or they may give you pain and headaches. Being aware of these gotchas will help you slay goblins should you encounter them on your journey to greatness. Take heed the warnings from your forefathers and foremothers for they have distilled onto you the knowledge so that you may succeed. Beware, ugly goblins ahead!

---

Avoid using DateTime.MinValue in your types

Bad things happen when DateTime.MinValue is used. For example, you might be tempted to use DateTime.MinValue:

DateTime.MinValue = 1/1/0001 12:00:00 AM

The minimum date time supported by RehtinkDB is:

1/1/1400

You will run into problems trying to store 0001 when the minimum is 1400. Use DateTime? nullable to indicate a time has not been set.

See Issue 49 and 66. Additionally, .NET Core DateTime.MinValue calculations are different between Windows and Linux platforms. See dotnet/corefx:Issue 9019.

The moral of story: Use DateTime? foo = null for MinValue.

---

$reql_type$ all up in my JObject

This won't work:

var items = Table("foo").RunAtomAsync<IEnumerable<JObject>>(conn);

This will:

var items = Table("foo").RunAtomAsync<JArray>(conn);

See Issue 65.

This also applies for the .RunChanges<T> run helper. .RunChanges<JObject> is just a simple wrapper for .RunCursor<Change<JObject>>. If the desired call is .RunChanges<JObject> simply use .RunCursor<JObject>() instead. See Issue 99.

---

if (expr == null) and the spirit of NullReferenceException

If you are building dynamic queries using ReQL terms, you might do something like:

if( expr == null )

And you'll get a mysterious exception. However, this will work:

if( ReferenceEquals(expr, null) )

See Issue 55.

---

High CPU load, ConnectionPool, .NET Core and Linux

Some users have experienced high CPU usage with .NET Core in Linux environments when attempting to use the ConnectionPool. This isn't particularly an issue with the driver; however, the reason behind high CPU load has to do with DNS resolution and IPv4 vs IPv6 connection addressing. It is recommended that you only use IPv4 addresses with connection pooling to avoid any high CPU load issues.

---

Connection issues especially with cloud providers or other hosted environments

Some users have reported seeing the following exceptions:

System.IO.IOException: Unable to read data from the transport connection
System.Net.Sockets.SocketException (10060): A connection attempt failed because the connected party did not properly respond after a period of time
RethinkDb.Driver.ReqlDriverError: Threads may not SendQuery because the connection is closed.

You'll want to make sure there is no additional hardware (like load balancers) that exist between the client application and the RethinkDB database. Some network devices (like HAProxy) can interfere with the driver connection leading to intermittent connection issues that produce log messages similar to "Threads may not SendQuery because the connection is shutting down."

In more detail, the problem is the underlying TCP/IP connection getting closed (or reset). The error messages above indicate that the thread responsible for reading server responses off the network socket received an exception from the operating system that a fatal networking error occurred. IE: The network error is fatal (and the driver is failing hard and early in this case to prevent surprises) such as queries possibly being sent and responses never being read back. The driver requires a persistent TCP/IP connection to RethinkDB. Under normal operating conditions, the TCP/IP connection must stay open for as long as your application wishes to use the driver.

Additionally, setting the driver's log level to Debug can provide more information about the error.

Special Note: Connections on Microsoft Azure, Amazon AWS, or other cloud providers

As stated above, connection issues are likely due to underlying network issues outside of the driver's control. Some cloud providers such as Microsoft Azure or Amazon AWS may have custom, modified, or optimized network stacks with finely tuned TCP timeouts and various NAT devices between the client application and the RethinkDB server.

Possible workarounds for connection issues

Possible workarounds for users is to do any or all of the following:

• Manually send a trivial query every minute to keep the connection alive. IE: Sending the query R.Expr("hello") should return "hello" in the response.
• Use Connection Pooling, even though you have one database server. If a connection drops, connection pooling code will try to reconnect automatically. You will still need to retry the query once the connection recovers.