`connectes_to` should only be called on `ActiveRecord::Base` or abstract
classes. This is recommended in the documentation but until now was not
enforced by the code. It's unsafe to open too many connections to mysql
(and probably other databases), so it's safest to have 1 class for the
connection and subclass from that.
Co-authored-by: NJohn Crepezzi <john.crepezzi@gmail.com>

If we enter a `connected_to` block and call `establish_connection` like
the test added here we need to ensure that `shard: current_shard` is passed
to the handler, otherwise the connection will be established on
`default` not on `shard_one`.
Co-authored-by: NJohn Crepezzi <john.crepezzi@gmail.com>

This change makes a helper method for resetting connection handlers in
the Active Record tests. The change here is relatively small and may
seem unnecessary. The reason we're pushing this change is for upcoming
refactoring to connection management. This change will mean that we can
update one location instead of 9+ files to reset connections. It will
reduce the diff of our refactoring and make reusing this code easier in
the future.

The method name chosen is purposefully `clean_up_connection_handler`
over `clean_up_connection_handlers` because in the future there will
only be one handler.
Co-authored-by: NJohn Crepezzi <john.crepezzi@gmail.com>

This change ensures that the connection methods are using kwargs instead
of positional arguments. This change may look unnecessary but we're
working on refactoring connection management to make it more robust and
flexible so the method signatures of the methods changed here will
continue to evolve and change.

This commit does not change any released public APIs. The `shard` and
`owner_name` arguments were added in 6.1 which is not released yet.
Using kwargs will allow these methods to be more flexible and not get
super ugly as we change their underlying behavior. The kwargs let us
support multiple non-positional arguments with default.
Co-authored-by: NJohn Crepezzi <john.crepezzi@gmail.com>

Applications can now connect to multiple shards and switch between
their shards in an application. Note that the shard swapping is
still a manual process as this change does not include an API for
automatic shard swapping.

Usage:

Given the following configuration:

```yaml
production:
  primary:
    database: my_database
  primary_shard_one:
    database: my_database_shard_one
```

Connect to multiple shards:

```ruby
class ApplicationRecord < ActiveRecord::Base
  self.abstract_class = true

  connects_to shards: {
    default: { writing: :primary },
    shard_one: { writing: :primary_shard_one }
  }
```

Swap between shards in your controller / model code:

```ruby
  ActiveRecord::Base.connected_to(shard: :shard_one) do
    # Read from shard one
  end
```

The horizontal sharding API also supports read replicas. See
guides for more details.

This PR also moves some no-doc'd methods into the private namespace as
they were unnecessarily public. We've updated some error messages and
documentation.
Co-authored-by: NJohn Crepezzi <john.crepezzi@gmail.com>