Function Connection.release

This method tells the server that it can dispose of the information it holds about the current prepared statement.

Calling this is not strictly necessary. The server considers prepared statements to be per-connection, so they'll go away when the connection closes anyway. This is provided in case direct control is actually needed.

If you choose to use a reference counted struct to call this automatically, be aware that embedding reference counted structs inside garbage collectible heap objects is dangerous and should be avoided, as it can lead to various hidden problems, from crashes to race conditions. (See the discussion at issue #159 for details.) Instead, it may be better to simply avoid trying to manage their release at all, as it's not usually necessary. Or to periodically release all prepared statements, and simply allow mysql-native to automatically re-register them upon their next use.

Notes

In actuality, the server might not immediately be told to release the statement (although isRegistered will still report false).

This is because there could be a ResultRange with results still pending for retrieval, and the protocol doesn't allow sending commands (such as "release a prepared statement") to the server while data is pending. Therefore, this function may instead queue the statement to be released when it is safe to do so: Either the next time a result set is purged or the next time a command (such as query or exec) is performed (because such commands automatically purge any pending results).

This function does NOT auto-purge because, if this is ever called from automatic resource management cleanup (refcounting, RAII, etc), that would create ugly situations where hidden, implicit behavior triggers an unexpected auto-purge.