This is kind of embarrassing, but I can't find how to test for db connection success or failure.
The documentation doesn't seem to cover it. I'm sure I've missed it. http://sequel.rubyforge.org/rdoc/files/doc/opening_databases_rdoc.html says that a Sequel::Database object is returned, which is true, but it does so on success and failure
So, two points: (1) How do you perform this test?, (2) Could the docs make this clearer, please.
The method is called Database#test_connection, and it is documented: http://sequel.rubyforge.org/rdoc/classes/Sequel/Database.html#method-i-test_connection. Sequel doesn't test the connection on Database object creation by default, but you can pass a :test=>true option or add ?test=t to the end of your connection string to do so.
If you think there is a better place to document this, please send a documentation pull request.
Thanks, Jeremy. I went down that method list a dozen times and failed to spot it.
Certainly, I believe that this should be more prominent, and I'll sort a pull request.
I think that a more ruby-ish method would be, say, connected?.
I also didn't spot the :test=>true option, but then I think that's the wrong name. The word "test" has a different connotation, imo. I'd use something like, force_connect, ensure_connected, or some such.
It's important to ensure the connection at start-up, particularly with daemon processes.
Well, the issue I have with connected? is that since it ends with ?, it should probably return false instead of raising an exception. As a connection failure is a fairly serious issue (usually the result of the database server being down or a misconfiguration), I think returning a boolean is less desirable than raising an error.
I see how :test=>true could be misinterpreted as implying use of a test database, but in practice that hasn't been an issue. I don't think :force_connect=>true or :ensure_connected=>true would be better. You can't force a connection or ensure a connection if the database server is down. I'm open to adding an additional option if a significantly better name could be found. The best alternative name I can think of now is :check=>true, but I don't think that's better enough to justify the addition.
I'd appreciate a pull request. However, if you don't have time for that, maybe just let me know where specifically in the documentation you think I should add the information, and what information I should add.
I thought test_connection was called after Sequel.connect and returned a boolean. But, as you say, it raises an exception. Again, the docs don't state the return value, so it requires a test to determine the result. Better to state: return Sequel::DatabaseConnectionError or true?
I maintain that the word test is unsatisfactory. But it's not a deal breaker.
Well, it doesn't return an error, it raises an error. The RDoc for the method currently states: "Attempts to acquire a database connection. Returns true if successful. Will probably raise an Error if unsuccessful. If a server argument is given, attempts to acquire a database connection to the given server/shard." Do you think this could be worded better?
I do think that check would have been a better word choice than test, but the test_connection method name dates back to before I took over maintenance of Sequel. I don't think we should add an alias unless there is a significantly better name.