# exdb.connect

Create a connection to one or more databases through an eXtremeSQL engine.

### Prototype

        Connection exdb.connect(dbname, port, nodes, nReplicas, maxConnectAttempts,
                useConnectionPool=useConnectionPool,
                txBufSize=txBufSize, localDomain=local,
                connectTimeout=2000L, readTimeout=1200*1000L,
                sql_login=sql_login, sql_password=sql_password,
                ssl_params=ssl_params,
                async=async, nworkers=nWorkers)

### Arguments

dbname | The database name or host IP: when `port` is specified, connect to a remote database; otherwise connect to the local database (conventional or shared memory) by `dbname`
port | The port to connect on; when specified connect to a remote database using the host (extracted from `dbname`) and specified `port`
nodes | The nodes list; when specified connect to distributed databases using the host and port values specified in `nodes`
nReplicas | The number of HA replicas; this number should be a divider of the number of `nodes` meaning that the remainder of `nNodes / nReplicas` is `0`. For example, the values of `nNodes` and `nReplicas` could be (4 and 2) or (12 and 3) but not (6 and 4) because 6 % 4 = 2
maxConnectAttempts | The maximum number of attempts to connect to distributed nodes or HA replicas
useConnectionPool | If true, then create a connection pool to enable parallel query execution for sequences
txBufSize | Specifies the size of transmit buffer used to serialize requests to be sent to the server (default is 64k)
localDomain | Indicates that Unix Domain Socket instead of networked TCP socket is used for RSQL communication which is possible only when server and client are on the same host
connectTimeout | The timeout for each connect attempt in milliseconds; so the total connection time can be up to `connectTimeout * maxConnectionAttempts` milliseconds
readTimeout | The timeout for read operations in milliseconds
sql_login | Login username when authentication is required
sql_password | Login password when authentication is required
ssl_params | A pointer to a `mco_ssl_params_t` structure containing SSL connection settings
async | When `True` create an AsyncDistributedConnection using `nworkers` processes to perform multiple queries on the distributed database shards specified in `nodes`
nworkers | When `async=True`, create `nworkers` processes to perform multiple queries on the distributed database shards specified in `nodes`

### Description

This method creates a connection to an eXtremeSQL engine. The connection will be of one of four SQL engine types:

- When arguments `dbname` is specified and `port` is null, a single Connection to a local database is returned (the database can be in conventional or shared memory depending on the runtime loaded),
- When argument `port` is specified the host name is extracted from argument `dbname`, and a RemoteConnection to a single database is returned,
- When argument `nodes` is specified a DistributedConnection is returned using the `nodes` and `maxConnectAttempts` arguments to create an eXtremeDB High Availability operating on master and replica databases or an eXtremeDB Cluster network of nodes operating on multiple databases or database shards,
- If argument `async=True` is specified, then an AsyncDistributedConnection is returned with `nworkers` processes created for parallel asynchronous execution of multiple queries.

### Returns

Connection | The connection to the SQL engine of the type determined by the arguments as explained above

### Examples

The following code snippet demonstrates creating connections of different types:

        ''' Connect to a local in-memory database in conventional memory (with Connection)

        '''
        is_shm = False
        is_debug = True
        is_disk = False
        tmgr='mursiw'
        exdb.init_runtime(is_disk, tmgr, is_shm, is_debug)
        conn = exdb.connect(dbname='imdb')

        ''' Connect to a local in-memory database in shared memory (with Connection)

        '''
        is_shm = True
        is_debug = True
        is_disk = False
        tmgr='mursiw'
        exdb.init_runtime(is_disk, tmgr, is_shm, is_debug)
        conn = exdb.connect(dbname='shmdb')

        ''' Connect to a remote database (with RemoteConnection)

        '''
        is_shm = False
        is_debug = True
        is_disk = False
        tmgr='mursiw'
        exdb.init_runtime(is_disk, tmgr, is_shm, is_debug)
        conn = exdb.connect('localhost', 5001)

        ''' Connect to two remote databases (with DistributedConnection)

        '''
        is_shm = False
        is_debug = True
        is_disk = False
        tmgr='mursiw'
        nodes = ("localhost:5001", "localhost:5002")
        exdb.init_runtime(is_disk, tmgr, is_shm, is_debug)
        conn = exdb.connect(nodes)

        ''' Connect to three remote databases (with AsyncDistributedConnection)

        '''
        is_shm = False
        is_debug = True
        is_disk = False
        tmgr='mursiw'
        nodes = ('bogota01:5000', 'bogota02:5001', 'bogota03:5000')
        exdb.init_runtime(is_disk, tmgr, is_shm, is_debug)
        conn = exdb.connect(nodes, async=True, nWorkers=5) )