To perform store operations, you must establish a network connection between your client code and the store. There are three pieces of information that you must provide:
The name of the store. The name provided here must be identical to the name used when the store was installed.
The network contact information for one or more helper hosts. These are the network name and port information for nodes currently running in the store. Multiple nodes can be identified. You can use one or many. Many does not hurt. The downside of using one is that the chosen host may be temporarily down, so it is a good idea to use more than one.
Identify the host and port where the proxy is running. You also do this using the configuration object.
If you are connecting to a secured store, you must also provide some authentication information. This is described in Setting the Security Properties for a Proxy Server.
For example, suppose you have an Oracle NoSQL Database store named "kvstore" and it has a node running on n1.example.org at port 5000. Further, suppose you are running your proxy on the localhost using port 7010. Then you would open and close a connection to the store in the following way:
from nosqldb import ConnectionException
from nosqldb import Factory
from nosqldb import StoreConfig
import logging
import sys
storehost = "n1.example.org:5000"
proxy = "localhost:7010"
# configure and open the store
def open_store():
try:
kvstoreconfig = StoreConfig('kvstore', [storehost])
return Factory.open(proxy, kvstoreconfig)
except ConnectionException, ce:
logging.error("Store connection failed.")
logging.error(ce.message)
sys.exit(-1)
Factory.open() returns a
Store class object, which you use to
perform most operations against your store. When you are done
with this handle, close it using the
close() method:
store = open_store() ... # Do store operations here ... store.close()
If you are using a secure store, then your proxy server must first be configured to authenticate to the store. See Securing Oracle NoSQL Database Proxy Server for details.
Once your proxy server is capable of accessing the secure store,
you must at a minimum indicate which user your driver wants to
authenticate as when it performs store access. To do this, use
the StoreConfig.set_user()
method.
For more information on using secure stores, see Working with a Secured Store .
# configure and open the store
def open_store():
try:
kvstoreconfig = StoreConfig('kvstore', [storehost])
kvstoreconfig.set_user("pythonapp-user")
return Factory.open(proxy, kvstoreconfig)
except ConnectionException, ce:
logging.error("Store connection failed.")
logging.error(ce.message)
sys.exit(-1)
If it is not already running, your client code will
automatically start the proxy server on the local host when
it opens the store so long as it can locate the
kvclient.jar and
kvproxy.jar files. These are
automatically installed when you install the nosqldb
driver, so you should not normally need to do anything
extra in order to have the driver automatically start the
proxy server.
However, if you installed the nosqldb driver in a non-standard location, or if you want to override the default jar files installed on your system, then you can explicitly tell the driver where these jar files are located:
If they are specified as parameters to the
ProxyConfig constructor,
then that location is used.
If that information is not specified to the
constructor, then it is taken from the
KVSTORE_JAR and
KVPROXY_JAR environment
variables.
If neither of the above methods are used, then the
driver uses the default jar files, which are
installed in
<python-site-packages-dir>/nosqldb/kvproxy/lib
In the following example, two environment variables are defined like this:
export KVSTORE_JAR="/d1/nosqldb-x.y.z/kvproxy/lib/kvclient.jar" export KVPROXY_JAR="/d1/nosqldb-x.y.z/kvproxy/lib/kvproxy.jar"
Because these environment variables are set, the
ProxyConfig constructor will
automatically use them as the location for the jar files.
# configure and open the store
def open_store():
kvstoreconfig = StoreConfig('kvstore', [kvlite])
kvproxyconfig = ProxyConfig()
return Factory.open(proxy, kvstoreconfig, kvproxyconfig)
Be aware that if your proxy is connecting to a secure store, you also must indicate which user to authenticate as, and you must indicate where the security properties file is located on the host where the proxy server is running.
# configure and open the store
def open_store():
kvstoreconfig = StoreConfig('kvstore', [kvlite])
kvstoreconfig.set_user("pythonapp-user")
kvproxyconfig = ProxyConfig()
kvproxyconfig.set_security_properties_file("/etc/proxy/sec.props")
return Factory.open(proxy, kvstoreconfig, kvproxyconfig)
For information on configuring your proxy server to connect to a secure store, see Securing Oracle NoSQL Database Proxy Server.
The
StoreConfig
class is used to
describe properties about a Store
handle. Most of the properties are optional; however, you must
identify the store name and helper hosts.
The properties that you can provide using
StoreConfig
are:
set_consistency()
Consistency is a property that describes how likely it is that a record read from a replica node is identical to the same record stored on a master node. For more information, see Consistency Guarantees.
set_durability()
Durability is a property that describes how likely it is that a write operation performed on the master node will not be lost if the master node is lost or is shut down abnormally. For more information, see Durability Guarantees.
set_max_results()
The number of rows buffered by iterators.
set_read_zones()
An array of zone names to be used as read zones. For more information on read zones, see the Oracle NoSQL Database Administrator's Guide.
set_request_timeout()
Configures the amount of time the client will wait for an operation to complete before it times out.
set_helper_hosts()
Helper hosts are hostname/port pairs that identify where nodes within the store can be contacted. Multiple hosts can be identified using an array of strings. Typically an application developer will obtain these hostname/port pairs from the store's deployer and/or administrator. For example:
conf.set_helper_hosts(['n1.example.org:3333','n2.example.org:3333'])
set_store_name()
Identifies the name of the store.
set_user()
The name of the user you want to authenticate to the store as. This property should only be used when your proxy server is configured to connect to a secure store.
The
ProxyConfig
class is used to describe properties about the proxy server you
are using to connect to the store.
The number of properties you can specify using this class are too numerous to describe here (see the Oracle NoSQL Python Driver for Tables API Reference for a complete listing), but the most common properties you will set are:
set_security_props_file()
The properties file containing the security information required to connect to a secure store. For information on secure stores and security properties, see Setting the Security Properties for a Proxy Server.
set_kv_store_path_to_jar()
The path where the kvstore.jar file is located. This information is only required if you are attempting to automatically start the proxy server.
set_kv_proxy_path_to_jar()
The path where the kvproxy.jar file is located. This information is only required if you are attempting to automatically start the proxy server.