Warning

This is work in progress and only available on the development branch

Postgres Database Manipulation API

This is the API for creating and dropping postgres users and databases used by the verdi quicksetup commandline tool. It allows convenient access to this functionality from within python without knowing details about how postgres is installed by default on various systems. If the postgres setup is not the default installation, additional information will have to be provided.

The Postgres Class

class aiida.control.postgres.Postgres(port=None, interactive=False, quiet=True)

Provides postgres database manipulation assuming no prior setup

• Can be used to create the initial aiida db user and database.
• Works in every reasonable environment, provided the user can sudo

Tries to use psychopg2 with a fallback to psql subcommands (using sudo su to run as postgres user).

Parameters:

• port – (str) Assume the database server runs on this port
• interactive – (bool) Allow prompting the user for information Will also be passed to sudo (if using psycopg2 fails) and to the callback that can be set to be called when automatic setup detection fails
• quiet – (bool) Suppress messages

Simple Example:

postgres = Postgres()
postgres.determine_setup()
postgres.create_dbuser('username', 'password')
if not postgres.db_exists('dbname'):
    postgres.create_db('username', 'dbname')

Complex Example:

postgres = Postgres(port=5433, interactive=True)
postgres.setup_fail_callback = prompt_db_info
postgres.determine_setup()
if postgres.pg_execute:
    print('setup sucessful!')

create_db(dbuser, dbname)

Create a database in postgres

Parameters:

• dbuser – (str), Name of the user which should own the db.
• dbname – (str), Name of the database.

create_dbuser(dbuser, dbpass)

Create a database user in postgres

Parameters:

• dbuser – (str), Name of the user to be created.
• dbpass – (str), Password the user should be given.

db_exists(dbname)

Check wether a postgres database with dbname exists

Parameters:dbname – Name of the database to check for Returns:(bool), True if database exists, False otherwise

dbuser_exists(dbuser)

Find out if postgres user with name dbuser exists

Parameters:dbuser – (str) database user to check for Returns:(bool) True if user exists, False otherwise

determine_setup()

Find out how postgres can be accessed.

Depending on how postgres is set up, psycopg2 can be used to create dbs and db users, otherwise a subprocess has to be used that executes psql as an os user with the right permissions.

drop_db(dbname)

Drop a database in postgres

Parameters:dbname – (str), Name of the database.

drop_dbuser(dbuser)

Drop a database user in postgres

Parameters:dbuser – (str), Name of the user to be dropped.

set_port(port)

Set the port manually

set_setup_fail_callback(callback)

Set a callback to be called when setup cannot be determined automatically

Parameters:callback – a callable with signature callback(interactive, dbinfo)

Further utilities

aiida.control.postgres.manual_setup_instructions(dbuser, dbname)

Create a message with instructions for manually creating a database

aiida.control.postgres.prompt_db_info(*args)

Prompt interactively for postgres database connecting details

Can be used as a setup fail callback for aiida.control.postgres.Postgres

Returns:dictionary with the following keys: host, port, database, user