Skip to content

Commit 6a8b32e

Browse files
anthony-tuiningaanthony-tuininga
committed
Improve documentation.
1 parent d35c4d6 commit 6a8b32e

File tree

1 file changed

+170
-119
lines changed

1 file changed

+170
-119
lines changed

‎doc/src/user_guide/connection_handling.rst

Lines changed: 170 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,11 @@ of Oracle Database's naming methods:
290290
:ref:`tnsnames.ora <optnetfiles>` file
291291
* An :ref:`LDAP URL <ldapurl>`
292292

293+
The ``dsn`` can additionally refer to a :ref:`Centralized Configuration
294+
Provider <builtinconfigproviders>`. The following providers are supported:
295+
296+
* :ref:`File Configuration Provider <fileconfigprovider>`
297+
293298
Connection strings used for JDBC and Oracle SQL Developer need to be altered to
294299
be usable as the ``dsn`` value, see :ref:`jdbcconnstring`.
295300

@@ -502,6 +507,170 @@ This can be referenced in python-oracledb:
502507
503508
connection = oracledb.connect(user="hr", password=userpwd, dsn="finance")
504509
510+
.. _builtinconfigproviders:
511+
512+
Centralized Configuration Providers
513+
===================================
514+
515+
Oracle Database Centralized Configuration Providers allow the storage and
516+
management of database connection credentials and application configuration
517+
information in a central location.
518+
519+
A configuration provider is used by setting the ``dsn`` parameter of connection
520+
and pool creation methods to specify where the configuration is located. For
521+
example to use connection configuration stored in a local file
522+
``/opt/oracle/my-config.json``:
523+
524+
.. code-block:: python
525+
526+
connection = oracledb.connect(user="hr", password=userpwd,
527+
dsn="config-file:///opt/oracle/my-config.json")
528+
529+
The following providers are supported by python-oracledb:
530+
531+
* :ref:`File Configuration Provider <fileconfigprovider>`
532+
533+
.. _fileconfigprovider:
534+
535+
Connecting Using the File Configuration Provider
536+
------------------------------------------------
537+
538+
The file configuration provider enables the storage and management of Oracle
539+
Database connection information as JSON in a file on your local file system.
540+
541+
When a connection or pool creation method is called with the prefix
542+
``config-file://`` for its ``dsn`` parameter, a built-in :ref:`connection hook
543+
function <connectionhook>` is internally invoked. This function parses the DSN
544+
and loads the configuration information which is stored in the specified file
545+
as JSON. The hook function sets the connection information in its
546+
``connect_params`` parameter. This :ref:`ConnectParams <connparam>` object is
547+
used by python-oracledb to establish a connection to Oracle Database.
548+
549+
The configuration file must contain at least the database connection
550+
string. Optionally, you can add the database user name, password, and
551+
python-oracledb specific properties. The JSON properties that can be added to
552+
the file are listed in the table below.
553+
554+
.. list-table-with-summary:: JSON properties for the File Configuration Provider
555+
:header-rows: 1
556+
:class: wy-table-responsive
557+
:widths: 15 25 15
558+
:name: _file_configuration_provider
559+
:summary: The first column displays the name of the property. The second column displays its description. The third column displays whether the sub-object is required or optional.
560+
561+
* - Sub-object
562+
- Description
563+
- Required or Optional
564+
* - ``user``
565+
- The database user name.
566+
- Optional
567+
* - ``password``
568+
- The password of the database user, or a dictionary containing the key "type" and password type-specific properties.
569+
- Optional
570+
* - ``connect_descriptor``
571+
- The database :ref:`connection string <connstr>`. The file must contain this property.
572+
- Required
573+
* - ``pyo``
574+
- Python-oracledb specific settings.
575+
- Optional
576+
577+
See the `Oracle Net Service Administrator’s Guide <https://www.oracle.com/pls/
578+
topic/lookup?ctx=dblatest&id=GUID-B43EA22D-5593-40B3-87FC-C70D6DAF780E>`__ for
579+
more information on these sub-objects.
580+
581+
.. warning::
582+
583+
Storing passwords in the configuration file should only ever be used in
584+
development or test environments.
585+
586+
When using the password type handler for "base64", a warning message will
587+
be generated: "base64 encoded passwords are insecure".
588+
589+
590+
**Sample File Configuration Provider syntax**
591+
592+
.. _singlefileconfiguration:
593+
594+
The following sample is an example of the File Configuration Provider syntax::
595+
596+
{
597+
"user": "scott",
598+
"password": {
599+
"type": "base64",
600+
"value": "dGlnZXI="
601+
},
602+
"connect_descriptor": "dbhost.example.com:1522/orclpdb",
603+
"pyo": {
604+
"stmtcachesize": 30,
605+
"min": 2,
606+
"max": 10
607+
}
608+
}
609+
610+
.. _multiplefileconfigurations:
611+
612+
Multiple configurations can be defined by using keys as shown in the example
613+
below. The key values are user-chosen::
614+
615+
{
616+
"production": {
617+
"connect_descriptor": "localhost/orclpdb"
618+
},
619+
"testing": {
620+
"connect_descriptor": "localhost/orclpdb",
621+
"user": "scott",
622+
"password": {
623+
"type": "base64",
624+
"value": "dGlnZXI="
625+
}
626+
}
627+
}
628+
629+
**Sample Using a File Configuration Provider**
630+
631+
To use a provider file, specify the ``dsn`` parameter of
632+
:meth:`oracledb.connect()`, :meth:`oracledb.create_pool()`,
633+
:meth:`oracledb.connect_async()`, or :meth:`oracledb.create_pool_async()` using
634+
the following format::
635+
636+
config-file://<file-path-and-name>[?key=<key>]
637+
638+
The parameters of the ``dsn`` parameter are detailed in the table below.
639+
640+
.. list-table-with-summary:: Connection String Parameters for File Configuration Provider
641+
:header-rows: 1
642+
:class: wy-table-responsive
643+
:widths: 20 60
644+
:name: _connection_string_for_file_configuration_provider
645+
:summary: The first column displays the name of the connection string parameter. The second column displays the description of the connection string parameter.
646+
647+
* - Parameter
648+
- Description
649+
* - ``config-file``
650+
- Indicates that the centralized configuration provider is a file in your local system.
651+
* - <file-name>
652+
- The file path (absolute or relative path) and name of the JSON file that contains the configuration information. For relative paths, python-oracledb will use the ``config_dir`` value to create an absolute path.
653+
* - ``key``
654+
- The connection key name used to identify a specific configuration. If this parameter is specified, the file is assumed to contain multiple configurations that are indexed by the key. If not specified, the file is assumed to contain a single configuration.
655+
656+
For example, if you have a configuration file in
657+
``/opt/oracle/my-config1.json`` with a :ref:`single configuration
658+
<singlefileconfiguration>` you could use it like:
659+
660+
.. code-block:: python
661+
662+
connection = oracledb.connect(user="hr", password=userpwd,
663+
dsn="config-file:///opt/oracle/my-config1.json")
664+
665+
If you have a configuration file in ``/opt/oracle/my-config2.json`` with
666+
:ref:`multiple configurations <multiplefileconfigurations>` you could use it like:
667+
668+
.. code-block:: python
669+
670+
connection = oracledb.connect(user="hr", password=userpwd,
671+
dsn="config-file:///opt/oracle/my-config2.json?key=production")
672+
673+
505674
.. _usingconnparams:
506675

507676
Using the ConnectParams Builder Class
@@ -2561,6 +2730,7 @@ It is recommended to use python-oracledb's local :ref:`connpooling` where
25612730
possible instead of implicit connection pooling. This gives multi-user
25622731
applications more control over pooled server reuse.
25632732

2733+
25642734
.. _proxyauth:
25652735

25662736
Connecting Using Proxy Authentication
@@ -4031,125 +4201,6 @@ typically the same directory where the ``wallet.zip`` file was extracted.
40314201
23ai. They contain important bug fixes for using multiple wallets in
40324202
the one process.
40334203

4034-
.. _builtinconfigproviders:
4035-
4036-
Connecting Using the File Centralized Configuration Provider
4037-
============================================================
4038-
4039-
The file configuration provider enables the storage and management of Oracle
4040-
Database connection information in a JSON file on your local file system. You
4041-
must add the connect descriptor in the file. Optionally, you can add the
4042-
database user name, password, and python-oracledb specific properties in the
4043-
file. The sub-objects that can be added to the JSON file are listed in the
4044-
table below.
4045-
4046-
.. list-table-with-summary:: Sub-objects for JSON File in File Configuration Provider
4047-
:header-rows: 1
4048-
:class: wy-table-responsive
4049-
:widths: 20 60
4050-
:name: _file_configuration_provider
4051-
:summary: The first column displays the name of the sub-object. The second column displays the description of the sub-object.
4052-
4053-
* - Sub-object
4054-
- Description
4055-
* - ``user``
4056-
- The database user name.
4057-
* - ``password``
4058-
- The password of the database user or a dictionary containing "type" and password type specific properties.
4059-
* - ``connect_descriptor``
4060-
- The :ref:`connect descriptor <conndescriptor>` value.
4061-
* - ``pyo``
4062-
- The python-oracledb specific attributes.
4063-
4064-
See `Oracle Net Service Administrator’s Guide <https://www.oracle.com/pls/
4065-
topic/lookup?ctx=dblatest&id=GUID-B43EA22D-5593-40B3-87FC-C70D6DAF780E>`__ for
4066-
more information on these sub-objects.
4067-
4068-
The following sample is an example of the configuration information defined in
4069-
a JSON file that is stored in a local file system::
4070-
4071-
{
4072-
"user": "scott",
4073-
"password": {
4074-
"type": "base64",
4075-
"value": "dGlnZXI="
4076-
},
4077-
"connect_descriptor": "dbhost.example.com:1522/orclpdb",
4078-
"pyo": {
4079-
"stmtcachesize": 30,
4080-
"min": 2,
4081-
"max": 10
4082-
}
4083-
}
4084-
4085-
.. _multipleconfigurations:
4086-
4087-
Multiple configurations can be defined in a JSON file by using keys as
4088-
shown in the example below::
4089-
4090-
{
4091-
"key1": {
4092-
"connect_descriptor": "localhost/orclpdb"
4093-
},
4094-
"key2": {
4095-
"connect_descriptor": "localhost/orclpdb",
4096-
"user": "scott",
4097-
"password": {
4098-
"type": "base64",
4099-
"value": "dGlnZXI="
4100-
}
4101-
}
4102-
}
4103-
4104-
You can use python-oracledb to access the configuration information stored in
4105-
a JSON file on your local file system. For this, you must specify the
4106-
connection string URL in the ``dsn`` parameter of :meth:`oracledb.connect()`,
4107-
:meth:`oracledb.create_pool()`, :meth:`oracledb.connect_async()`, or
4108-
:meth:`oracledb.create_pool_async()` in the following format::
4109-
4110-
config-file://<file-name>?key=<key>
4111-
4112-
The parameters of the connection string are detailed in the table below.
4113-
4114-
.. list-table-with-summary:: Connection String Parameters for File Configuration Provider
4115-
:header-rows: 1
4116-
:class: wy-table-responsive
4117-
:widths: 20 60
4118-
:name: _connection_string_for_file_configuration_provider
4119-
:summary: The first column displays the name of the connection string parameter. The second column displays the description of the connection string parameter.
4120-
4121-
* - Parameter
4122-
- Description
4123-
* - ``config-file``
4124-
- Indicates that the centralized configuration provider is a file in your local system.
4125-
* - <file-name>
4126-
- The file path (absolute or relative path) and name of the JSON file that contains the configuration information. For relative paths, python-oracledb will use the ``config_dir`` value to create an absolute path.
4127-
* - ``key``
4128-
- The connection key name used to identify a specific configuration. If this parameter is specified, the file is assumed to contain multiple configurations that are indexed by the key. If not specified, the file is assumed to contain a single configuration.
4129-
4130-
For example, to access the "myfile.json" JSON file and the "key2" configuration
4131-
from the :ref:`multiple configurations sample <multipleconfigurations>` shown
4132-
above:
4133-
4134-
.. code-block:: python
4135-
4136-
configfileurl = "config-file://myfile.json?key=key2"
4137-
oracledb.connect(dsn=configfileurl)
4138-
4139-
When :meth:`oracledb.connect()` is called, the built-in hook function to handle
4140-
connection strings prefixed with ``config-file://`` is
4141-
internally invoked. This hook function parses the connection string and
4142-
extracts the name of the JSON file containing the configuration information
4143-
and the connection key name that is stored in your local file system. Using
4144-
these details, this hook function accesses the configuration information
4145-
stored in the JSON file. The hook function sets the connection information
4146-
from the JSON file in its ``connect_params`` parameter. This ConnectParams
4147-
object is used by python-oracledb to establish a connection to Oracle
4148-
Database.
4149-
4150-
Note that when using the password type handler for "base64", a warning will be
4151-
generated: "base64 encoded passwords are insecure".
4152-
41534204
.. _connsharding:
41544205

41554206
Connecting to Oracle Globally Distributed Database

0 commit comments

Comments
 (0)