Skip to main content

Overview

This docs details how to connect a Python application to Oxla running inside a Docker container using the Psycopg2 library. Psycopg2 is a PostgreSQl adapter for Python programming language. It allows you to execute SQL queries and interact with your Oxla instance using Python and is designed for multi-threaded applications that create and destroy lots of cursors (more on them here) and make a large number of concurrent INSERTs or UPDATEs.

Prerequisites

Before you begin, make sure you have the following installed:
  • Docker
  • Python (preferably with a virtual environment)
  • The Psycopg2 library

Running Oxla Docker Container

  1. Open your terminal
  2. Pull and run Oxla Docker container using the following command:

Establishing Connection

To connect to Oxla using Psycopg2, use the psycopg2.connect() function. It creates a new database session and returns a connection object.
  • Using keyword arguments:
The following parameters can be used with the psycopg2.connect() function:
  • dbname: your database connection name (i.e. “oxla_node_1”)
  • user: username to authenticate with (i.e. “oxla”, which is the default username)
  • password: password to authenticate with (i.e. “oxla”, which is the default password)
  • host: localhost or 127.0.0.1
  • Port: default for PostgreSQL is 5432

Example Usage

Here’s an example on how to connect to Oxla using keyword arguments:
It is important to note that Oxla does not support multi-threaded transactions as provided by Psycopg2. This means that when using Oxla, you must be cautious when it comes to managing connections and transactions within a multi-threaded context.
Now, let’s define some table, insert data into it and query inserted data.

Supported Features And Limitations

While Oxla supports many core SQL features, some limitations exist, in particular related to transaction handling and certain advanced Psycopg2 functionalities. This section clarifies which functions are fully supported, which have limited support and which are currently unavailable.

Supported Features

  • Basic Connection and Cursor Management You can use psycopg2.connect() to establish connections and create cursors with conn.cursor() to execute SQL commands.
  • SQL Execution Standard SQL commands such as CREATE TABLE, INSERT, SELECT, UPDATE and DELETE are supported and can be executed via cursor.execute().
  • Transaction Control Basic transaction commands like conn.commit() and conn.rollback() are available but Oxla currently has limited transaction support and does not support multi-threaded transactions.
  • Error Handling Psycopg2 exceptions such as psycopg2.errors can be caught and handled normally.

Limitations and Unsupported Features

  • Multi-threaded Transactions Oxla does not support multi-threaded transactions as Psycopg2 normally provides. Avoid sharing connections or cursors across threads when performing transactional operations.
  • Advanced Psycopg2 Features Features such as server-side cursors, asynchronous communication, notifications, prepared statements and pipeline mode may not be fully supported due to Oxla’s current architecture.

Oxla - Psycopg2 Feature Compatibility Table