The source code listing is below, anything not explained in the subsequent lines is already covered by the previous tutorials.

001 #!/usr/bin/env python
002 
003 import matplotlib
004 from matplotlib import pyplot as plot
005 
006 import cx_Oracle
007 
008 query = """select name, (ratio_to_report(value) over() ) * 100
009               from v$sga"""
010 
011 connection_string = "pyuser/pypassword@orcl"
012 
013 connection = cx_Oracle.Connection(connection_string)
014 cursor = cx_Oracle.Cursor(connection)
015 cursor.execute(query)
016 
017 pie_labels = []
018 pie_data   = []
019 
020 for row in cursor.fetchall():
021   pie_labels.append(row[0])
022   pie_data.append(row[1])
023 
024 figure = plot.figure()
025 
026 axis = figure.add_subplot(111)
027 axis.pie(pie_data, labels=pie_labels)
028 axis.legend(pie_data, loc='best')
029 
030 plot.show()

008-009 ratio_to_report

This query uses the ratio_to_report oracle function to return every row as a ratio of the sum of the rows.   Multiplying by 100 results in a percentage which is perfect for use with pie charts.   Note that you won’t always want to use percentages, sometimes the actual value supplies more information.

017-018 Labels and Data

These lines declare two arrays that will be used to store the labels and values retrieved from the database.

027 axis.pie(pie_data, labels=pie_labels)

In line 27 we see a new command.  This is the command used to generate a pie-chart, and in the simple form as it is here, it takes two arguments.  The first is an array of data to be used for the plot and the second is an array containing the corresponding labels for the data.

028 axis.legend(pie_data, loc=’best’)

The final line of note is 28,  where we create and place the chart legend.  The two arguments to supply in this case are the data array and the positioning of the legend.  The ‘best’ flag means that matplotlib will try to automatically place the legend in an appropriate location.  Other positioning flags you could use are:

• upper right
• upper left
• lower left
• lower right
• right
• center left
• center right
• lower center
• upper center
• center

Below we can see the final result.

Pie Chart

As is customary by now, we begin with the source code:

001 import matplotlib
002 from matplotlib import pyplot as plot
003 
004 import cx_Oracle
005 
006 query = """select size_factor as "Size Factor",
007            estd_physical_reads as "Physical Reads"
008            from v$db_cache_advice
009            where block_size = 8192
010            order by size_factor"""
011 
012 connection_string = "system/systempwd@PYTEST"
013 connection = cx_Oracle.Connection(connection_string)
014 cursor = cx_Oracle.Cursor(connection)
015 cursor.execute(query)
016 column_names = cursor.description
017 
018 x_data = []
019 y_data = []
020 
021 for row in cursor.fetchall():
022   x_data.append(row[0])
023   y_data.append(row[1])
024 
025 figure = plot.figure()
026 axis = figure.add_subplot(111)
027 axis.plot(x_data, y_data, '-')
028 
029 plot.xlabel(column_names[0][0])
030 plot.ylabel(column_names[1][0])
031 
032 plot.show()

At first glance this may look like a lot of code, but not much has changed from what was covered in the first tutorials.

001-002 New Imports

These two lines import what we need from matplotlib.  Notice that the as keyword is used to explicitly set an identifier for an imported module.  You can see this identifier being used in line 025.

006-010 Multiline text

In this part of the program a sql query is written spanning multiple lines.  To create a multiline text string in Python you use three double quotes to start the string and three double qoutes to indicate the end.  This is very useful, especially when working with long strings like pieces of SQL.  This query selects advice for the 8K database cache from the v$db_cache_advice table.

018-019 Arrays

Recall from earlier tutorials that Python does not require you to explicitly define the type of variable you are declaring.  In these two lines we are creating two arrays.  Each array is indicated by square brackets.  One array will store the values for the x-axis and the other will store the values for the y-axis.

021-023 for-loop

These lines contain a for-loop that fetches all the values in the first column into the x-axis array and all the values from the second column into the y-axis array.

025-027 matplotlib magic

This part of the code is responsible for plotting the data that we have collected.  Line 25 defines a figure.  This figure is a container for one or more axes. Line 26 creates an axes.  The axes is the part of the plot that we are all familiar with.   It consists of the x- and y-axis as well as the area where the chart is plotted.  The 111 syntax here indicates 1 row, 1 column and 1 subplot meaning, in short, that there is only 1 axes in this figure.  Line 27 plots the data from our arrays and ‘-’ indicates that we are using a solid line plot.

029-030 Reusable Axis Labels

To make this code reusable the axis labels are retrieved from the query using the well know cursor.description data.  This way we can change the program by only altering the query, and the labels will be changed automatically.  You can test this by replacing 006-010 with the following:

006 query = """select pga_target_factor as "Size Factor",
007            estd_pga_cache_hit_percentage "Cache Hit %"
008            from v$pga_target_advice
009            order by pga_target_factor
010            """

032 plot.show()

Finally we display the plot we have generated (click on the image for a larger view):

This plot only shows the base functionality of matplotlib, but it is a good example of the simplicity of using the library and its power.

001 import cx_Oracle
002 
003 query = "select * from v$database"
004 connection_string = "system/systempassword@PYTEST"
005 
006 connection = cx_Oracle.Connection(connection_string)
007 cursor = cx_Oracle.Cursor(connection)
008 cursor.execute(query)
009 
010 column_names = cursor.description
011 
012 for row in cursor.fetchall():
013   c = 0
014   for column in row:
015     print str(column_names[c][0]) + ": " + str(column)
016     c += 1
017 
018 cursor.close()

The next step is to have a look at what is new in this code.

003 query = “select * from v$database”

The first line of interest is the new query we are running.  Seeing as this tutorial series wants to introduce DBAs to python, we now have a query that will be at least vaguely useful to a DBA.

004 connection_string = “system/systempassword@PYTEST”

This time we need to connect as a user with the privilege to select from the v$database view.

010 column_names = cursor.description

The cx_Oracle cursor object has an attribute called description which holds MetaData about the columns we are using.  In this example we will be extracting the column name using this attribute.  The column name is the first item in this sequence.

013   c = 0

To keep track of the column number that is currently being processed, we declare a variable called c which is initiated to 0, the first item in a series.

015     print str(column_names[c][0]) + “: ” + str(column)

In line 15 we print two things.  The column_names[c][0] statement displays the name of every column and then the str(column) part displays the value contained in that column.  Note that we are casting the column as a string to make sure that it can be concatenated with the column name.  String concatenation is acheived by using the + symbol.

016     c += 1

In lines 16 we increment the value of c to reference the number of the next column.

This simple program displays all the values in the v$database table formatted in a very readable way.  Also notice that a table with one row is visualised as a set of attribute-value pairs.

Before it could go into Beta I finished University and the project was sadly left neglected. Since then new developments in hardware and software tools have revolutionised hair/fur/fibre modelling and animation.

It is a great memory in so many ways, and that is where I got hooked on the beauty and simplicity of Python.

In addition to having an Oracle Database, the requirements for this tutorial are listed below:

• Python - At the time of writing this I used 2.5
• cx_Oracle – The module for connecting to Oracle Databases

The code below shows a connection being made to an Oracle Database and some data being returned and displayed.  This is a trimmed-down version without error checking.

Note:  Like many bloggers before me, I ran into the problem of posting code on a blog here.  This is my first attempt, but I’m not entirely happy with the format and, therefore, it will be updated at a later stage.

001  import cx_Oracle
002  
003  query = "select 'Hello World!!' from dual"
004  connection_string = "SCOTT/TIGER@PYTEST"
005  
006  connection = cx_Oracle.Connection(connection_string)
007  cursor = cx_Oracle.Cursor(connection)
008  cursor.execute(query)
009
010  for row in cursor.fetchall():
011    for column in row:
012      print column
013
014  cursor.close()
015  connection.close()

Now we can start analysing what is happening line by line.

001 – import cx_Oracle

Python modules are used to extend the functionality of your application.  For example, if you want to use mathematical functions like sin, pi and sqrt you need to import the math module (import math).

In this case we are importing the cx_Oracle module, which was designed for connecting to Oracle databases and conforms to the Python Database API Specification. This module makes interacting with the Oracle Database really straight forward, as we will see in the following sections.

003  query = “select ‘Hello World!!’ from dual”

This sets a variable containing the text which is the query to be executed.  This query does not do much, but the idea is to keep the example simple.  Two things are important to note:

• Python automatically “knows” what kind of variable you are declaring.  You do not have to explicitly specify the type.
• The string is wrapped in double quotes and the singe quotes are handled correctly.

004  connection_string = “SCOTT/TIGER@PYTEST”

In this line another string variable is declared, this time containing the connection string of the database.

006  connection = cx_Oracle.Connection(connection_string)

The connection object is created by using the connection string declared in line 004.  Note that this line uses the cx_Oracle module.  Assuming that the supplied connection string is correct, this is all that is needed to create the connection.

007  cursor = cx_Oracle.Cursor(connection)

A connection alone does not get much done.  The object doing the work in this case is the cursor.  Working with Oracle we should all be familiar with cursors.  This python cursor is similar to an explicit PL/SQL cursor and is used to retrieve rows/columns from a table.

008  cursor.execute(query)

Executing the cursor gets us to the point where we can start retrieving data.  The query variable declared earlier is used to specify the source data for the cursor.  There will be a future post detailing what is happening in the background at each of these stages.

010-012 for loop

Retrieving the data is accomplished by using two for loops.  The first loop returns every row, the second loop is nested in the first loop and works within the row, returning the value of every column.  In line 012 the current column is printed for every row.

This generic approach means that the results of most queries can be handled by this script, and changing the data accessed by the script is as easy as changing the SQL statement stored in the query variable.

014 – 015  *.close()

Although cursors and connections are closed automatically when the program terminates, it is good practise to close these explicitly when you are done with them.

I will try to be accurate and scientific in my approach, because it is very easy to confuse facts with what you want to be true.

In conclusion I would like to ask anyone for input on what they think python and oracle can be used for and also what you would like to see examples and explanations of.