{"id":7992,"library":"borneo","title":"Oracle NoSQL Database Python SDK","description":"Borneo is the official Python SDK for Oracle NoSQL Database, version 5.4.3. It provides interfaces for developing Python applications that connect to the Oracle NoSQL Database Cloud Service, on-premise Oracle NoSQL Database, and the Oracle NoSQL Cloud Simulator. The library is actively maintained with regular feature releases and bug fixes, typically on a quarterly or bi-annual cadence.","status":"active","version":"5.4.3","language":"en","source_language":"en","source_url":"https://github.com/oracle/nosql-python-sdk","tags":["database","nosql","oracle","cloud","sdk"],"install":[{"cmd":"pip install borneo","lang":"bash","label":"Core SDK"},{"cmd":"pip install oci","lang":"bash","label":"Required for Cloud Service authentication"}],"dependencies":[{"reason":"Required for authenticating with Oracle NoSQL Database Cloud Service.","package":"oci","optional":true}],"imports":[{"symbol":"NoSQLHandle","correct":"from borneo import NoSQLHandle"},{"symbol":"NoSQLHandleConfig","correct":"from borneo import NoSQLHandleConfig"},{"symbol":"Regions","correct":"from borneo import Regions"},{"symbol":"SignatureProvider","correct":"from borneo.iam import SignatureProvider"},{"symbol":"TableLimits","correct":"from borneo import TableLimits"},{"symbol":"TableRequest","correct":"from borneo import TableRequest"},{"symbol":"PutRequest","correct":"from borneo import PutRequest"},{"symbol":"GetRequest","correct":"from borneo import GetRequest"},{"symbol":"DeleteRequest","correct":"from borneo import DeleteRequest"}],"quickstart":{"code":"import os\nimport time\nfrom borneo import (\n    NoSQLHandle,\n    NoSQLHandleConfig,\n    Regions,\n    TableLimits,\n    TableRequest,\n    PutRequest,\n    GetRequest,\n    DeleteRequest\n)\nfrom borneo.iam import SignatureProvider\nfrom borneo.exception import NoSQLException, InvalidAuthorizationException\n\n# --- Configure OCI Credentials and Region ---\n# Replace with your actual OCI configuration or set environment variables\n# OCI_REGION can be found at https://docs.oracle.com/en-us/iaas/Content/General/Concepts/regions.htm\n# OCI_TENANCY, OCI_USER, OCI_FINGERPRINT are from your OCI API Key setup\n# OCI_PRIVATE_KEY_PATH points to your private key file (e.g., ~/.oci/oci_api_key.pem)\n# OCI_PRIVATE_KEY_PASSPHRASE is optional if your key is passphrase-protected\n\nregion = os.environ.get('OCI_REGION', 'us-ashburn-1') # e.g., Regions.US_ASHBURN_1\ntenancy_id = os.environ.get('OCI_TENANCY_ID', '')\nuser_id = os.environ.get('OCI_USER_ID', '')\nfingerprint = os.environ.get('OCI_FINGERPRINT', '')\nprivate_key_path = os.environ.get('OCI_PRIVATE_KEY_PATH', os.path.expanduser('~/.oci/oci_api_key.pem'))\nprivate_key_passphrase = os.environ.get('OCI_PRIVATE_KEY_PASSPHRASE', '')\n\n# Configure table details\ntable_name = \"myUserTable\"\ncompartment_id = os.environ.get('OCI_COMPARTMENT_ID', tenancy_id) # Use tenancy_id if compartment_id is not specifically set\n\n\ndef get_nosql_handle():\n    try:\n        provider = SignatureProvider(\n            tenant_id=tenancy_id,\n            user_id=user_id,\n            fingerprint=fingerprint,\n            private_key_file=private_key_path,\n            private_key_passphrase=private_key_passphrase\n        )\n        config = NoSQLHandleConfig(region, provider)\n        config.set_default_compartment(compartment_id)\n        return NoSQLHandle(config)\n    except InvalidAuthorizationException as e:\n        print(f\"Authentication failed: {e}\")\n        print(\"Please ensure OCI_REGION, OCI_TENANCY_ID, OCI_USER_ID, OCI_FINGERPRINT, \"\n              \"and OCI_PRIVATE_KEY_PATH environment variables are correctly set \"\n              \"or hardcoded with valid OCI credentials.\")\n        return None\n\ndef create_and_wait_for_table(handle):\n    table_limits = TableLimits(10, 10, 1)\n    statement = f'CREATE TABLE IF NOT EXISTS {table_name} (id INTEGER, name STRING, age INTEGER, PRIMARY KEY (id))'\n    request = TableRequest().set_statement(statement).set_table_limits(table_limits)\n\n    print(f\"Creating table {table_name}...\")\n    try:\n        table_result = handle.do_table_request(request, 20000, 1000) # timeout_ms, polling_interval_ms\n        print(f\"Table {table_name} created and is in state: {table_result.get_state()}\")\n    except NoSQLException as e:\n        print(f\"Error creating table: {e}\")\n        # Check if the table already exists, which might be acceptable\n        if \"Table already exists\" not in str(e):\n            raise\n\ndef put_and_get_data(handle):\n    # Put a row\n    put_request = PutRequest().set_table_name(table_name).set_value({'id': 1, 'name': 'Alice', 'age': 30})\n    put_result = handle.put(put_request)\n    print(f\"Put row: {put_result.get_version()}\")\n\n    # Get the row\n    get_request = GetRequest().set_table_name(table_name).set_key({'id': 1})\n    get_result = handle.get(get_request)\n    if get_result.get_value():\n        print(f\"Get row: {get_result.get_value()}\")\n    else:\n        print(\"Row not found.\")\n\ndef delete_table(handle):\n    statement = f'DROP TABLE IF EXISTS {table_name}'\n    request = TableRequest().set_statement(statement)\n\n    print(f\"Dropping table {table_name}...\")\n    try:\n        table_result = handle.do_table_request(request, 20000, 1000)\n        print(f\"Table {table_name} dropped and is in state: {table_result.get_state()}\")\n    except NoSQLException as e:\n        print(f\"Error dropping table: {e}\")\n\nif __name__ == '__main__':\n    handle = None\n    try:\n        handle = get_nosql_handle()\n        if not handle:\n            exit(1)\n\n        create_and_wait_for_table(handle)\n        put_and_get_data(handle)\n    finally:\n        if handle:\n            delete_table(handle) # Clean up the table\n            handle.close()\n            print(\"NoSQLHandle closed.\")\n","lang":"python","description":"This quickstart connects to Oracle NoSQL Database (Cloud Service, Simulator, or On-Premise) using OCI credentials provided via environment variables. It demonstrates how to create a table, put a record, retrieve a record by its primary key, and finally drop the table, cleaning up resources. For cloud connections, ensure the `oci` package is installed and your OCI API key configuration (tenancy_id, user_id, fingerprint, private_key_path, optional passphrase, and compartment_id) is correctly set in environment variables or hardcoded."},"warnings":[{"fix":"Upgrade your Python environment to 3.5 or newer before upgrading to borneo 5.4.1 or later.","message":"Version 5.4.1 (and subsequent 5.x releases) dropped support for Python 2.x. The SDK now only supports Python 3.5 and higher.","severity":"breaking","affected_versions":"5.4.1+"},{"fix":"Replace `handle.table_request(request)` and `result.wait_for_completion()` with a single call to `handle.do_table_request(request, timeout_ms, polling_interval_ms)`.","message":"The pattern of calling `NoSQLHandle.table_request()` followed by `TableResult.wait_for_completion()` is deprecated. The method `NoSQLHandle.do_table_request()` should be used instead for asynchronous table operations.","severity":"deprecated","affected_versions":"5.1.0+"},{"fix":"Upgrade to borneo version 5.3.5 or later. Ensure the `oci` package is installed (`pip install oci`) and that your OCI credentials are correctly configured, as the `SignatureProvider` relies on the `oci` SDK.","message":"When using the cloud service, older versions (prior to 5.3.5) of `borneo` might encounter `NameError: name 'auth' is not defined` if `oci` is not correctly configured or imported in `iam.py`.","severity":"gotcha","affected_versions":"<5.3.5"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install oci` to install the Oracle Cloud Infrastructure SDK.","cause":"The `oci` package, required for Oracle NoSQL Database Cloud Service authentication, is not installed.","error":"ModuleNotFoundError: No module named 'oci'"},{"fix":"Verify all OCI credentials and region settings. Ensure the IAM user has policies granting `manage nosql-tables` and `use nosql-rows` permissions in the specified compartment/tenancy.","cause":"Incorrect OCI API key configuration (e.g., wrong tenancy_id, user_id, fingerprint, private_key_path, or compartment_id), or the OCI user lacks the necessary IAM policies for Oracle NoSQL Database.","error":"borneo.exception.InvalidAuthorizationException: Not authorized to perform this operation. <details about auth>"},{"fix":"Use `NoSQLHandle.do_table_request()` or explicitly poll `TableResult.wait_for_completion()` after a `TableRequest` to ensure the table reaches the `TableState.ACTIVE` state before proceeding with data operations.","cause":"Table creation is an asynchronous operation. The application attempted to perform operations on the table before it transitioned to an 'ACTIVE' state.","error":"borneo.exception.NoSQLException: Table 'myUserTable' is not in a terminal state for create operation, current state: CREATING"}]}