Skip to content

Commit d789762

Browse files
gmfeinberggmfeinberg
committed
Added quickstart tutorial to README. Minor doc updates.
1 parent 44835d8 commit d789762

File tree

2 files changed

+354
-10
lines changed

2 files changed

+354
-10
lines changed

‎README.rst

Lines changed: 349 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -61,14 +61,6 @@ The `documentation <https://nosql-python-sdk.readthedocs.io/en/latest>`_ has
6161
information on using the SDK as well as an `API reference <https://nosql-python-
6262
sdk.readthedocs.io/en/latest/api.html>`_ describing the classes.
6363

64-
===========
65-
Development
66-
===========
67-
68-
The `development readme <https://github.com/oracle/nosql-python-sdk/blob/master/
69-
README-DEV.rst>`_ has information about running tests and examples, building the
70-
documentation, and other development activities.
71-
7264
=======
7365
Changes
7466
=======
@@ -84,12 +76,359 @@ The nosql-python-sdk is an open source project. See `Contributing <https://
8476
github.com/oracle/nosql-python-sdk/blob/master/CONTRIBUTING.rst>`_ for
8577
information on how to contribute to the project.
8678

79+
==========
80+
Quickstart
81+
==========
82+
83+
The following is a quick start tutorial to run a simple program in the supported
84+
environments. The same template source code is used for all environments. The
85+
first step is to cut the program below and paste it into an editor for minor
86+
modifications. The instructions assume that is stored as quickstart.py, but you
87+
can use any name you like. The quickstart example supports 3 environments:
88+
89+
1. Oracle NoSQL Database Cloud Service
90+
2. Oracle NoSQL Cloud Simulator
91+
3. Oracle NoSQL Database on-premise, using the proxy server
92+
93+
See `Running Quickstart <#run-quickstart>`_ for instructions on how to edit and
94+
run the quickstart program in different environments. The instructions assume
95+
that the *borneo* package has been installed.
96+
97+
.. code-block:: pycon
98+
99+
#
100+
# Copyright (C) 2018, 2020 Oracle and/or its affiliates. All rights reserved.
101+
#
102+
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl
103+
#
104+
# Please see LICENSE.txt file included in the top-level directory of the
105+
# appropriate download for a copy of the license and additional information.
106+
#
107+
108+
#
109+
# This is a simple quickstart to demonstrate use of the Python driver for the
110+
# Oracle NoSQL Database. It can be used to run against the Oracle NoSQL Database
111+
# Cloud Service, against the Cloud Simulator, or against an on-premise Oracle
112+
# NoSQL database.
113+
#
114+
# Usage:
115+
# python quickstart.py <cloud|cloudsim|kvstore>
116+
#
117+
# Use cloud for the Cloud Service
118+
# Use cloudsim for the Cloud Simulator
119+
# Use kvstore for the on-premise database
120+
#
121+
# This example is not intended to be an exhaustive overview of the API, which
122+
# has a number of additional operations.
123+
#
124+
# Requirements:
125+
# 1. Python 2.7 or 3.5+
126+
# 2. Python dependencies (install using pip or other mechanism):
127+
# o requests
128+
# o oci (only if running against the Cloud Service)
129+
# 3. If running against the Cloud Simulator, it can be downloaded from here:
130+
# http://www.oracle.com/technetwork/topics/cloud/downloads/index.html
131+
# It requires Java
132+
# 4. If running against the Oracle NoSQL Database Cloud Service an account must
133+
# be used.
134+
#
135+
136+
import sys
137+
138+
from borneo import (
139+
AuthorizationProvider, DeleteRequest, GetRequest, IllegalArgumentException,
140+
NoSQLHandle, NoSQLHandleConfig, PutRequest, QueryRequest, Regions,
141+
TableLimits, TableRequest)
142+
from borneo.iam import(SignatureProvider)
143+
from borneo.kv import(StoreAccessTokenProvider)
144+
145+
146+
#
147+
# EDIT: these values based on desired region and/or endpoint for a local server
148+
#
149+
cloud_region = Regions.EU_ZURICH_1
150+
cloudsim_endpoint = 'localhost:8080'
151+
kvstore_endpoint = 'localhost:80'
152+
cloudsim_id = 'cloudsim' # a fake user id/namespace for the Cloud Simulator
153+
154+
# Cloud Service Only
155+
#
156+
# EDIT: set these variables to the credentials to use if you are not using
157+
# a configuration file in ~/.oci/config
158+
# Use of these credentials vs a file is determined by a value of
159+
# tenancy other than None.
160+
#
161+
tenancy = None # tenancy'd OCID (string)
162+
user = None # user's OCID (string)
163+
private_key = 'path-to-private-key-or-private-key-content'
164+
fingerprint = 'fingerprint for uploaded public key'
165+
pass_phrase = None # pass phrase (string) for private key, or None if not set
166+
167+
class CloudsimAuthorizationProvider(AuthorizationProvider):
168+
"""
169+
Cloud Simulator Only.
170+
171+
This class is used as an AuthorizationProvider when using the Cloud
172+
Simulator, which has no security configuration. It accepts a string
173+
id that is used as a simple namespace for tables.
174+
"""
175+
176+
def __init__(self, id):
177+
super(CloudsimAuthorizationProvider, self).__init__()
178+
self._id = id
179+
180+
def close(self):
181+
pass
182+
183+
def get_authorization_string(self, request=None):
184+
return 'Bearer ' + self._id
185+
186+
187+
def get_handle(nosql_env):
188+
"""
189+
Returns a NoSQLHandle based on the requested environment. The differences
190+
among the supported environments are encapsulated in this method.
191+
"""
192+
provider = None
193+
endpoint = None
194+
195+
if nosql_env == 'cloud':
196+
endpoint = cloud_region
197+
#
198+
# Get credentials using SignatureProvider. SignatureProvider
199+
# has several ways to accept credentials. See the documentation:
200+
# https://nosql-python-sdk.readthedocs.io/en/latest/api/borneo.iam.SignatureProvider.html
201+
#
202+
if tenancy is not None:
203+
print('Using directly provided credentials')
204+
#
205+
# Credentials are provided directly
206+
#
207+
provider = SignatureProvider(tenant_id = tenancy,
208+
user_id = user,
209+
fingerprint = fingerprint,
210+
private_key = private_key,
211+
pass_phrase = pass_phrase)
212+
else:
213+
#
214+
# Credentials will come from a file.
215+
#
216+
# By default the file is ~/.oci/config. A config_file = <path>
217+
# argument can be passed to specify a different file.
218+
#
219+
print('Using credentials and DEFAULT profile from ~/.oci/config')
220+
provider = SignatureProvider()
221+
elif nosql_env == 'cloudsim':
222+
print('Using cloud simulator endpoint ' + cloudsim_endpoint)
223+
endpoint = cloudsim_endpoint
224+
provider = CloudsimAuthorizationProvider(cloudsim_id)
225+
226+
elif nosql_env == 'kvstore':
227+
print('Using on-premise endpoint ' + kvstore_endpoint)
228+
endpoint = kvstore_endpoint
229+
provider = StoreAccessTokenProvider()
230+
231+
else:
232+
raise IllegalArgumentException('Unknown environment: ' + nosql_env)
233+
234+
return NoSQLHandle(NoSQLHandleConfig(endpoint, provider))
235+
236+
def main():
237+
238+
table_name = 'PythonQuickstart'
239+
240+
if len(sys.argv) != 2:
241+
print('Usage: python quickstart.py <cloud|cloudsim|kvstore>')
242+
raise SystemExit
243+
244+
nosql_env = sys.argv[1:][0]
245+
print('Using environment: ' + str(nosql_env))
246+
247+
handle = None
248+
try:
249+
250+
#
251+
# Create a handle
252+
#
253+
handle = get_handle(nosql_env)
254+
255+
#
256+
# Create a table
257+
#
258+
statement = ('Create table if not exists {} (id integer, ' +
259+
'sid integer, name string, primary key(shard(sid), id))').format(table_name)
260+
request = TableRequest().set_statement(statement).set_table_limits(
261+
TableLimits(30, 10, 1))
262+
handle.do_table_request(request, 50000, 3000)
263+
print('After create table')
264+
265+
#
266+
# Put a few rows
267+
#
268+
request = PutRequest().set_table_name(table_name)
269+
for i in range(10):
270+
value = {'id': i, 'sid': 0, 'name': 'myname' + str(i)}
271+
request.set_value(value)
272+
handle.put(request)
273+
print('After put of 10 rows')
274+
275+
#
276+
# Get the row
277+
#
278+
request = GetRequest().set_key({'id': 1, 'sid': 0}).set_table_name(
279+
table_name)
280+
result = handle.get(request)
281+
print('After get: ' + str(result))
282+
283+
#
284+
# Query, using a range
285+
#
286+
statement = 'select * from ' + table_name + ' where id > 2 and id < 8'
287+
request = QueryRequest().set_statement(statement)
288+
result = handle.query(request)
289+
print('Query results for: ' + statement)
290+
for r in result.get_results():
291+
print('\t' + str(r))
292+
293+
#
294+
# Delete the row
295+
#
296+
request = DeleteRequest().set_key({'id': 1, 'sid': 0}).set_table_name(
297+
table_name)
298+
result = handle.delete(request)
299+
print('After delete: ' + str(result))
300+
301+
#
302+
# Get again to show deletion
303+
#
304+
request = GetRequest().set_key({'id': 1, 'sid': 0}).set_table_name(
305+
table_name)
306+
result = handle.get(request)
307+
print('After get (should be None): ' + str(result))
308+
309+
#
310+
# Drop the table
311+
#
312+
request = TableRequest().set_statement(
313+
'drop table if exists {} '.format(table_name))
314+
result = handle.table_request(request)
315+
316+
#
317+
# Table drop can take time, depending on the state of the system.
318+
# If this wait fails the table will still probably been dropped
319+
#
320+
result.wait_for_completion(handle, 40000, 2000)
321+
print('After drop table')
322+
323+
print('Quickstart is complete')
324+
except Exception as e:
325+
print(e)
326+
finally:
327+
# If the handle isn't closed Python will not exit properly
328+
if handle is not None:
329+
handle.close()
330+
331+
332+
if __name__ == '__main__':
333+
main()
334+
335+
.. _run-quickstart:
336+
337+
Running Quickstart
338+
------------------
339+
340+
Run Against the Oracle NoSQL Database Cloud Service
341+
===================================================
342+
343+
Running against the Cloud Service requires an Oracle Cloud account. See
344+
`Configure for the Cloud Service <https://nosql-python-sdk.readthedocs.io/en/latest/installation.html#configure-for-the-cloud-service>`_ for information on getting
345+
an account and acquiring required credentials.
346+
347+
1. Collect the following information:
348+
349+
* Tenancy ID
350+
* User ID
351+
* API signing key (private key file in PEM format)
352+
* Fingerprint for the public key uploaded to the user's account
353+
* Private key pass phrase, needed only if the private key is encrypted
354+
355+
2. Edit *quickstart.py* and add your information. There are 2 ways to supply
356+
credentials in the program:
357+
358+
* Directly provide the credential information. To use this method, modify the
359+
values of the variables at the top of the program: *tenancy*, *user*,
360+
*private_key*, *fingerprint*, and *pass_phrase*, setting them to the
361+
corresponding information you've collected.
362+
* Using a configuration file. In this case the information you've collected
363+
goes into a file, ~/.oci/config. `Configure for the Cloud Service <https://nosql-python-sdk.readthedocs.io/en/latest/installation.html#configure-for-the-cloud-service>`_ describes the contents of the file. It will look like this::
364+
365+
[DEFAULT]
366+
tenancy=<your-tenancy-id>
367+
user=<your-user-id>
368+
fingerprint=<fingerprint-of-your-public-key>
369+
key_file=<path-to-your-private-key-file>
370+
pass_phrase=<optional-pass-phrase-for-key-file>
371+
372+
3. Decide which region you want to use and modify the *cloud_region* variable to
373+
the desired region. See `Regions documentation <https://nosql-python-sdk.readthedocs.io/en/latest/api/borneo.Regions.html>`_ for possible regions. Not all support
374+
the Oracle NoSQL Database Cloud Service.
375+
376+
4. Run the program:
377+
378+
.. code-block:: pycon
379+
380+
python quickstart.py cloud
381+
382+
383+
Run Against the Oracle NoSQL Cloud Simulator
384+
============================================
385+
386+
Running against the Oracle NoSQL Cloud Simulator requires a running Cloud
387+
Simulator instance. See `Using the Cloud Simulator <https://oracle.github.io/nosql-node-sdk/tutorial-connect-cloud.html#cloudsim>`_ for information on how to download
388+
and start the Cloud Simulator.
389+
390+
1. Start the Cloud Simulator based on instructions above. Note the HTTP port
391+
used. By default it is *8080* on *localhost*.
392+
393+
2. The *quickstart.py* program defaults to *localhost:8080* so if the Cloud
394+
Simulator was started using default values no editing is required.
395+
396+
3. Run the program:
397+
398+
.. code-block:: pycon
399+
400+
python quickstart.py cloudsim
401+
402+
Run Against Oracle NoSQL on-premise
403+
===================================
404+
405+
Running against the Oracle NoSQL Database on-premise requires a running
406+
Oracle NoSQL Database instance as well as a running NoSQL Proxy server instance.
407+
The program will connect to the proxy server.
408+
409+
See `Connecting to an On-Premise Oracle NoSQL Database <https://oracle.github.io/nosql-node-sdk/tutorial-connect-on-prem.html>`_ for information on how to download
410+
and start the database instance and proxy server. The database and proxy should
411+
be started without security enabled for this quickstart program to operate
412+
correctly. A secure configuration requires a secure proxy and more complex
413+
configuration.
414+
415+
1. Start the Oracle NoSQL Database and proxy server based on instructions above.
416+
Note the HTTP port used. By default the endpoint is *localhost:80*.
417+
418+
2. The *quickstart.py* program defaults to *localhost:80*. If the proxy was started
419+
using a different host or port edit the settings accordingly.
420+
421+
3. Run the program:
422+
423+
.. code-block:: pycon
424+
425+
python quickstart.py kvstore
426+
87427
=======
88428
License
89429
=======
90430

91431
Copyright (C) 2018, 2020 Oracle and/or its affiliates. All rights reserved.
92432

93433
This SDK is licensed under the Universal Permissive License 1.0. See
94-
`LICENSE <https://github.com/oracle/nosql-python-sdk/blob/master/LICENSE.txt>`_
95-
for details
434+
`LICENSE <./LICENSE.txt>`_ for details

‎docs/installation.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,11 @@ connecting an application are associated with a specific user. If needed, create
105105
a user for the person or system using the api. See `Adding Users <https://docs.
106106
cloud.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm>`_.
107107

108+
Using the SDK with the Oracle NoSQL Database Cloud Service also requires
109+
installation of the Oracle Cloud Infrastructure (OCI) Python SDK::
110+
111+
pip install oci
112+
108113
.. _creds-label:
109114

110115
Acquire Credentials for the Oracle NoSQL Database Cloud Service

0 commit comments

Comments
 (0)