This document describes how to use SQLAlchemy, a Python SQL tool and object-relational mapping (ORM) tool, with YugabetyDB.

Prerequisites

  • YugabyteDB version 2.6 or later (see YugabyteDB Quick Start Guide).

  • Python version 2.7 or later.

  • The latest version of SQLAlchemy, which you can install using pip by executing the following command:

    pip3 install sqlalchemy
    

    Verify the installation as follows:

    • Open the Python prompt by executing the following command:

      python3
      
    • From the Python prompt, execute the following commands to check the SQLAlchemy version:

      import sqlalchemy
      
      sqlalchemy.version
      
  • Psycopg2, the PostgreSQL database adapter for Python, which you can install using pip by executing the following command:

    pip3 install psycopg2
    

    Alternatively, you can install psycopg2-binary, a pre-compiled version of the module, by executing the following command:

    pip3 install psycopg2-binary
    

Use SQLAlchemy

Start using SQLAlchemy with YugabyteDB as follows:

  • Create a demo project and add a main.py and config.py files to it.

  • Add the following code to the config.py file:

    db_user = 'yugabyte'
    db_password = 'yugabyte'
    database = 'yugabyte'
    db_host = 'localhost'
    db_port = 5433
    
  • Add the following code to the main.py file:

    import config as cfg
    from sqlalchemy.ext.declarative import declarative_base
    from sqlalchemy.orm import sessionmaker, relationship
    from sqlalchemy import create_engine
    from sqlalchemy import MetaData
    from sqlalchemy import Table, Column, Integer, String, DateTime, ForeignKey
    Base = declarative_base()
    
    class Test(Base):
    
       __tablename__ = 'test'
    
       id = Column(Integer, primary_key=True)
       name = Column(String(255), unique=True, nullable=False)
    
    # create connection
    engine = create_engine('postgresql://{0}:{1}@{2}:{3}/{4}'.format(cfg.db_user, cfg.db_password, cfg.db_host, cfg.db_port, cfg.database))
    
    # create metadata
    Base.metadata.create_all(engine)
    
    # create session
    Session = sessionmaker(bind=engine)
    session = Session()
    
    # insert data
    tag_1 = Test(name='Bob')
    tag_2 = Test(name='John')
    tag_3 = Test(name='Ivy')
    
    session.add_all([tag_1, tag_2, tag_3])
    session.commit()
    
  • Execute the code using the following command:

    python3 main.py
    

Test the code

Verify the code execution by looking for the changes inside the database as follows:

  • Navigate to your YugabyteDB installation directory by running the following command:

    cd /<path-to-yugabytedb>
    
  • Run the ysqlsh client by executing the following command:

    ./bin/ysqlsh
    
  • Obtain the list of all the tables in the database by executing the following command:

    \dt
    
  • Check if rows have been inserted into the table by executing the following:

    SELECT * FROM TEST;
    

    The output should be as follows:

    id | name
    ---+--------
     1 | Bob
     2 | John
     3 | Ivy
    (3 rows)
    

Limitations

Consider the following limitations:

  • Because of the distributed nature of YugabyteDB, rows returned by a query might not be in sequential or expected order. It is, therefore, recommended that you use the orderby() function to avoid the wrong data when executing functions such as first().
  • YugabyteDB does not support columns that contain a PRIMARY KEY of type user_defined_type.