Server Connection and Info#
There are a number of options available when connecting to a BTrDB server or server cluster. First, you will need to identify the appropriate IP or FQDN to use as well as the access port.
By default BTrDB servers expose port 4410 for unencrypted access and 4411 for encrypted access using TLS. You may also opt for authentication using an API key which can be provided to you by the BTrDB server administrators. Using such a key will require the TLS port (4411) as attempting to use a different port with an API key will raise an exception.
Connecting to servers#
The btrdb library comes with a high level connect
function to interface
with a BTrDB server. Upon successfully connecting, you will be returned a
BTrDB
object which is the starting point for all of your server
interactions.
For your convenience, you may default all connection parameters to environment
variables if these are configured on your system. If no arguments are provided, the
btrdb.connect
function will attempt to connect using the
BTRDB_ENDPOINTS
and BTRDB_API_KEY
environment variables.
Several connection options are shown in the code below:
import btrdb
# connect using BTRDB_ENDPOINTS and BTRDB_API_KEY ENV variables
conn = btrdb.connect()
# connect without credentials
conn = btrdb.connect("192.168.1.101:4410")
# connect without credentials using TLS
conn = btrdb.connect("192.168.1.101:4411")
# connect with API key
conn = btrdb.connect("192.168.1.101:4411", apikey="123456789123456789")
Using Profiles#
In addition to providing the endpoint and API key directly (or through environment variables), you may provide a profile name which looks into your PredictiveGrid credentials file at $HOME/.predictivegrid/credentials.yaml. Using profiles is meant as a (optional) convenience device and may also be supplied through the environmental variable $BTRDB_PROFILE.
import btrdb
# connect using your own "research" profile
conn = btrdb.connect(profile="research")
The credentials file is in YAML format as shown below.
research:
name: "research"
btrdb:
endpoints: "research.example.com:4411"
api_key: "d976a2d61103feb2235441fd6887955c"
default:
name: "default"
btrdb:
endpoints: "btrdb.example.com:4411"
api_key: "e666a2d61103feb2235441fd68879440"
Connection Info Resolution#
The connect
function is quite aggressive about finding ways to connect to the server
and power users could get into odd edge cases if using multiple profiles with incomplete entries.
For troubleshooting purposes, the connect
function performs the following steps to
determine the correct server credentials.
Load profile connection info with the
BTRDB_PROFILE
environment variable or load the default profile if not found.Overwrite the profile data with
BTRDB_ENDPOINTS
andBTRDB_API_KEY
environment variables if available.Overwrite accumulated connection data with
endpoints
andapi_key
arguments if supplied.
Viewing server status#
Server version and connection information can be viewed by calling the info
method of the server object as shown below.
conn = btrdb.connect()
conn.info()
>> {'majorVersion': 5, 'build': '5.0.0', 'proxy': {'proxyEndpoints': '192.168.1.101:4410'}}