Skip to content

Commit ddb2572

Browse files
anthony-tuiningaanthony-tuininga
committed
Documentation improvements.
1 parent 41b60b7 commit ddb2572

File tree

4 files changed

+125
-19
lines changed

4 files changed

+125
-19
lines changed

‎doc/src/api_manual/module.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3128,6 +3128,9 @@ parameter for the :meth:`Queue.enqone()`, :meth:`Queue.enqmany()`,
31283128
This constant is used to specify that enqueue should perform its work as
31293129
part of an independent transaction.
31303130

3131+
The use of this constant with :ref:`bulk enqueuing <bulkenqdeq>` is only
3132+
supported in python-oracledb :ref:`Thick mode <enablingthick>`.
3133+
31313134

31323135
.. data:: ENQ_ON_COMMIT
31333136

‎doc/src/release_notes.rst

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,11 +42,15 @@ Thick Mode Changes
4242
#) Fixed bug resulting in a segfault when unable to load the Oracle Client
4343
libraries
4444
(`ODPI-C <https://github.com/oracle/odpi>`__ dependency update).
45+
#) Fixed bug which resulted in error ``ORA-24328: illegal attribute value``
46+
when calling :meth:`Connection.gettype()` with Oracle Client 11.2
47+
libraries
48+
(`ODPI-C <https://github.com/oracle/odpi>`__ dependency update).
4549
#) Improved error message when getting :attr:`Connection.max_open_cursors`
46-
when using Oracle Client libraries 11.2
50+
when using Oracle Client 11.2 libraries
4751
(`ODPI-C <https://github.com/oracle/odpi>`__ dependency update).
4852
#) Improved error message when attempting to work with sparse vectors using
49-
Oracle Client libraries 23.6 or earlier
53+
Oracle Client 23.6 (or earlier) libraries
5054
(`ODPI-C <https://github.com/oracle/odpi>`__ dependency update).
5155

5256
Common Changes
@@ -80,6 +84,7 @@ Common Changes
8084
python-oracledb Thick mode raised the error ``DPI-1071: payload type in
8185
message properties must match the payload type of the queue`` and thin mode
8286
raised an internal error.
87+
#) Improved the test suite and documentation.
8388

8489

8590
oracledb 3.0.0 (March 2025)

‎doc/src/user_guide/aq.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,9 @@ types.
2626
- JSON payloads require Oracle Database 21c (or later). In python-oracle Thick
2727
mode, Oracle Client libraries 21c (or later) are also needed.
2828

29-
JMS payloads and :ref:`Recipient Lists <reciplists>` are only supported in
30-
python-oracledb :ref:`Thick mode <enablingthick>`.
29+
The use of :data:`~oracledb.ENQ_IMMEDIATE` with bulk enqueuing, JMS payloads,
30+
and :ref:`Recipient Lists <reciplists>` are only supported in python-oracledb
31+
:ref:`Thick mode <enablingthick>`.
3132

3233
There are examples of AQ Classic Queues in the `GitHub samples
3334
<https://github.com/oracle/python-oracledb/tree/main/samples>`__ directory.
@@ -338,6 +339,7 @@ expiration of 60 seconds on a message:
338339
This means that if no dequeue operation occurs within 60 seconds then the
339340
message will be dropped from the queue.
340341

342+
.. _bulkenqdeq:
341343

342344
Bulk Enqueue and Dequeue
343345
========================

‎doc/src/user_guide/lob_data.rst

Lines changed: 111 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _lobdata:
22

3-
************************
4-
Using CLOB and BLOB Data
5-
************************
3+
***************************************
4+
Using CLOB, BLOB, NCLOB, and BFILE Data
5+
***************************************
66

77
Oracle Database uses :ref:`LOB objects <lobobj>` to store large data such as
88
text, images, videos, and other multimedia formats. The maximum size of a LOB
@@ -11,21 +11,20 @@ text, images, videos, and other multimedia formats. The maximum size of a LOB
1111
There are `four types of LOBs <https://www.oracle.com/pls/topic/lookup?ctx=
1212
dblatest&id=GUID-0A692C1B-1C95-4121-8F95-25BE465B87F6>`__:
1313

14-
* BLOB - Binary Large Object, used for storing binary data. python-oracledb
15-
uses the type :attr:`oracledb.DB_TYPE_BLOB`.
1614
* CLOB - Character Large Object, used for storing strings in the database
1715
character set format. python-oracledb uses the type
1816
:attr:`oracledb.DB_TYPE_CLOB`.
17+
* BLOB - Binary Large Object, used for storing binary data. python-oracledb
18+
uses the type :attr:`oracledb.DB_TYPE_BLOB`.
1919
* NCLOB - National Character Large Object, used for storing strings in the
2020
national character set format. python-oracledb uses the type
2121
:attr:`oracledb.DB_TYPE_NCLOB`.
2222
* BFILE - External Binary File, used for referencing a file stored on the
2323
host operating system outside of the database. python-oracledb uses the
24-
type :attr:`oracledb.DB_TYPE_BFILE`. See `BFILEs <https://www.oracle.com
25-
/pls/topic/lookup?ctx=dblatest&id=GUID-D4642C92-F343-4700-9F1F-
26-
486F82249FB8>`__ for more information.
24+
type :attr:`oracledb.DB_TYPE_BFILE`.
2725

28-
LOBs can be streamed to, and from, Oracle Database.
26+
LOBs can be permanent or temporary. They can be inserted into, and fetched
27+
from, Oracle Database in chunks, as mecessary.
2928

3029
LOBs up to 1 GB in length can be also be handled directly as strings or bytes
3130
in python-oracledb. This makes LOBs easy to work with, and has significant
@@ -36,7 +35,7 @@ See `GitHub <https://github.com/oracle/python-oracledb/tree/main/samples>`__
3635
for LOB examples.
3736

3837
Simple Insertion of LOBs
39-
------------------------
38+
========================
4039

4140
Consider a table with CLOB and BLOB columns:
4241

@@ -69,7 +68,7 @@ Note that with this approach, LOB data is limited to 1 GB in size.
6968
.. _directlobs:
7069

7170
Fetching LOBs as Strings and Bytes
72-
----------------------------------
71+
==================================
7372

7473
CLOBs and BLOBs smaller than 1 GB can queried from the database directly as
7574
strings and bytes. This can be much faster than streaming a :ref:`LOB Object
@@ -121,7 +120,7 @@ handler:
121120
connection.outputtypehandler = output_type_handler
122121
123122
Streaming LOBs (Read)
124-
---------------------
123+
=====================
125124

126125
Without setting ``oracledb.defaults.fetch_lobs`` to False, or without using an
127126
output type handler, the CLOB and BLOB values are fetched as :ref:`LOB
@@ -168,7 +167,7 @@ repeatedly until all of the data has been read, as shown below:
168167
169168
170169
Streaming LOBs (Write)
171-
----------------------
170+
======================
172171

173172
If a row containing a LOB is being inserted or updated, and the quantity of
174173
data that is to be inserted or updated cannot fit in a single block of data,
@@ -196,9 +195,8 @@ in the following code:
196195
offset += len(data)
197196
connection.commit()
198197
199-
200198
Temporary LOBs
201-
--------------
199+
==============
202200

203201
All of the examples shown thus far have made use of permanent LOBs. These are
204202
LOBs that are stored in the database. Oracle also supports temporary LOBs that
@@ -214,3 +212,101 @@ procedure exceeds that which can fit in a single block of data, however, you
214212
can use the method :meth:`Connection.createlob()` to create a temporary LOB.
215213
This LOB can then be read and written just like in the examples shown above for
216214
persistent LOBs.
215+
216+
.. _bfiles:
217+
218+
Using BFILEs
219+
============
220+
221+
`BFILEs <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-D4642C92
222+
-F343-4700-9F1F-486F82249FB8>`__ are objects stored in a directory in the
223+
Oracle Database server file system, not in the database. The database column of
224+
type BFILE stores a reference to this external binary file. Each BFILE column
225+
can reference a single external file. BFILEs are read-only data types and
226+
hence you cannot modify the file from within your application.
227+
228+
Before using the BFILE data type, you must:
229+
230+
- Create a `DIRECTORY <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
231+
F7440C27-C7F0-4874-8C3C-F3BC1534CBE0>`__ object which is an alias for the
232+
full path to the directory containing BFILE data in the database server file
233+
system. For example, you can create a DIRECTORY object by using:
234+
235+
.. code-block:: sql
236+
237+
create or replace directory my_bfile_dir as '/demo/bfiles'
238+
239+
In the above example, "my_bfile_dir" is the directory alias.
240+
"/demo/bfiles" is the physical directory in the database server file
241+
system that contains the files. It is a string containing the full path name
242+
of the directory and follows the operating system rules.
243+
244+
To allow non-privileged users to access this directory, you can grant access
245+
using:
246+
247+
.. code-block:: sql
248+
249+
grant read on directory my_bfile_dir to hr;
250+
251+
Ensure that the Oracle Server processes have read access to the directory.
252+
253+
- Store the physical binary file in the directory in the database server file
254+
system. For example, the binary file "my_bfile.txt" is stored in the
255+
directory "/demo/bfiles".
256+
257+
Consider the file, "/demo/bfiles/my_bfile.txt", exists on the server and
258+
contains the text, "This is my BFILE data". You can access the "my_bfile.txt"
259+
file as detailed below.
260+
261+
The following table will be used in the subsequent examples.
262+
263+
.. code-block:: sql
264+
265+
create table bfile_tbl(
266+
id number,
267+
bfile_data bfile
268+
);
269+
270+
**Inserting BFILEs**
271+
272+
You must use the `BFILENAME <https://www.oracle.com/pls/topic/lookup?ctx=
273+
dblatest&id=GUID-1F767077-7C26-4962-9833-1433F1749621>`__ function in an INSERT
274+
statement to associate a file and a BFILE column. The ``BFILENAME`` function
275+
takes two arguments, the directory alias and the file name. To insert a BFILE
276+
reference, for example:
277+
278+
.. code-block:: python
279+
280+
cursor.execute("""
281+
insert into bfile_tbl (id, bfile_data) values
282+
(:id, bfilename(:bfiledir, :bfilename))""",
283+
id=102, bfiledir="my_bfile_dir", bfilename="my_bfile.txt")
284+
285+
connection.commit()
286+
287+
This inserts a reference to the file "my_bfile.txt" located in the directory
288+
referenced by the alias "my_bfile_dir" into the bfile_tbl table.
289+
290+
**Fetching BFILEs**
291+
292+
To query the bfile_tbl table and fetch the BFILE LOB locator, you can use
293+
the `BFILENAME <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
294+
1F767077-7C26-4962-9833-1433F1749621>`__ function as shown below:
295+
296+
.. code-block:: python
297+
298+
cursor.execute("select bfilename(:bfiledir, :bfilename) from bfile_tbl where id = :id",
299+
id=102, bfiledir="my_bfile_dir", bfilename="my_bfile.txt")
300+
bfile, = cursor.fetchone()
301+
print(bfile.read())
302+
303+
This will display::
304+
305+
This is my BFILE data
306+
307+
This fetched LOB can use :meth:`LOB.fileexists()` to check if the file
308+
referenced by the BFILE type LOB exists.
309+
310+
You can get the directory alias and file name of this fetched LOB by using
311+
:meth:`LOB.getfilename()`. Also, you can set the directory alias and file name
312+
for this fetched LOB by using :meth:`LOB.setfilename()`.

0 commit comments

Comments
 (0)