Managed Objects¶

Before trying any of the code below, connect to the cluster by running:

from pgmob import Cluster
cluster = Cluster(host="127.0.0.1", user="postgres", password="s3cur3p@ss")

Databases¶

Database objects are managing PostgreSQL databases. Even though we can only see a list of objects from the database we are currently connected to, Cluster object provides an interface to databases regardless of the currently active database.

### creating. modifying, and dropping databases
db = cluster.databases.new(database="mydb", template="mytemplatedb", owner="myuser", is_template=True)
cluster.databases.add(db)
cluster.databases["mydb"].name = "mynewdbname"
cluster.databases["mydb"].alter()
cluster.databases.refresh()
cluster.databases["mynewdbname"].drop()
### working with database collection
foo_db = cluster.databases.new(database="foo")
foo_db.create()
dir(foo_db)
for db in cluster.databases:
    print(db.name, db.is_template)
if foo_db.name in cluster.databases:
    foo_db.disable()
sql = foo_db.script().replace("foo", "bar")
cluster.execute(sql)

class pgmob.objects.Database(name: str, cluster: Cluster = None, parent: DatabaseCollection = None, owner: str = None, encoding: str = None, collation: str = None, is_template: bool = False, oid: int | None = None, from_template: str = None)¶

Postgres Database object. Represents a database object on a Postgres server.

Parameters:

cluster (str) – Postgres cluster object
name (str) – name of the database
owner (str) – Database owner
encoding (str) – Database encoding
collation (str) – Database collation
is_template (bool) – True if the database is a template
oid (int) – Database OID
parent (DatabaseCollection) – parent collection

name¶

Database name

Type:: str

owner¶

Database owner

Type:: str

encoding¶

Database encoding

Type:: str

collation¶

Database collation

Type:: str

character_type¶

Database character type

Type:: str

is_template¶

True if the database is a template

Type:: bool

allow_connections¶

True if the database accepts connections

Type:: bool

connection_limit¶

Database connection limit

Type:: int

last_sys_oid¶

Last system object ID

Type:: int

frozen_xid¶

Frozen transaction ID

Type:: str

min_multixact_id¶

Minimum multi-transaction ID

Type:: str

tablespace¶

Default tablespace

Type:: str

acl¶

Database access list

Type:: str

oid¶

Database OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

create()¶: Create a database on the Postgres cluster

disable(terminate_connections: bool = False)¶

Disallows connections to a database by modifying pg_database.datallowconn.

Parameters:: terminate_connections (bool) – Force all connections to be dropped after disabling the database

drop(terminate_connections: bool = False)¶

Drops the database represented by this object

Parameters:: terminate_connections (bool) – Force all connections to be terminated after disabling the database

enable()¶: Enables connections to a database by modifying pg_database.datallowconn

refresh()¶: Re-initializes the object, refreshing its properties

script(as_composable: bool = False) → str | Composable¶

Generate a database creation script.

Parameters:: as_composable (bool) – return Composable object instead of plain text
Returns:: database creation script
Return type:: Union[str, Composable]

class pgmob.objects.DatabaseCollection(cluster: Cluster)¶

An iterable collection of databases indexed by database name.

add(database: Database)¶

Adds the database object to the collection, simultaneously creating it on the cluster

Parameters:: database (Database) – initialized database object

new(name: str, template: str | None = None, owner: str | None = None, is_template: bool = False, encoding: str | None = None, collation: str | None = None) → Database¶

Create a database object on the current Postgres cluster. The object is created ephemeral and either needs to be added to the database collection, or .create() needs to be executed.

Parameters:

name (str) – The name of the database
template (str) – Name of the template database to use
owner (str) – Owner of the database
encoding (str) – Database encoding
collation (str) – Sets LC_COLLATE and LC_CTYPE for the database
is_template (bool) – whether the database is a template

refresh()¶: Resets any pending changes and retrieves child objects from the cluster

Roles¶

Role objects represent PostgreSQL roles (or users). It is a classic Managed Object that can be created, scripted, modified, and dropped.

### creating, modifying, and dropping roles
cluster.roles.new(name="myrole", password="mypassword", superuser=True, replication=True, login=False, connection_limit=20).create()
cluster.roles.refresh()
cluster.roles["myrole"].change_password("mynewpassword")
cluster.roles["myrole"].superuser = False
cluster.roles["myrole"].replication = False
cluster.roles["myrole"].login = True
cluster.roles["myrole"].connection_limit = -1
cluster.roles["myrole"].alter()
cluster.roles["myrole"].drop()
### working with role collection
dir(cluster.roles["somerole"])
for role in cluster.roles:
    print(role.name, role.login)
if "somerole" in cluster.roles:
    sql = cluster.roles["somerole"].script()
    cluster.execute(sql.replace("somerole", "newrole"))

class pgmob.objects.Role(name: str, password: str = None, cluster: Cluster = None, superuser: bool = False, inherit: bool = True, createrole: bool = False, createdb: bool = False, login: bool = False, replication: bool = False, bypassrls: bool = False, connection_limit: int = -1, valid_until: datetime = None, oid: int = None, parent: RoleCollection = None)¶

Postgres Role object. Represents a role object on a Postgres server.

Parameters:

name (str) – name of the role
password (str) – role password with which it will be created
cluster (str) – Postgres cluster object
superuser (bool) – SUPERUSER permissions
inherit (bool) – INHERIT permissions
createrole (bool) – CREATEROLE permissions
createdb (bool) – CREATEDB permissions
login (bool) – LOGIN permissions
replication (bool) – REPLICATION permissions
bypassrls (bool) – BYPASSRLS enabled
connection_limit (int) – Role connection limit
valid_until (datetime) – Expires on this date
oid (int) – Role OID
parent (DatabaseCollection) – parent collection

name¶

Table name

Type:: str

cluster¶

Postgres cluster object

Type:: str

superuser¶

SUPERUSER permissions

Type:: bool

inherit¶

INHERIT permissions

Type:: bool

createrole¶

CREATEROLE permissions

Type:: bool

createdb¶

CREATEDB permissions

Type:: bool

login¶

LOGIN permissions

Type:: bool

replication¶

REPLICATION permissions

Type:: bool

bypassrls¶

BYPASSRLS enabled

Type:: bool

connection_limit¶

Role connection limit

Type:: int

valid_until¶

Expires on this date

Type:: datetime

oid¶

Role OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

change_password(password: str) → None¶

Changes the role’s password

Parameters:: password (str) – new password

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

create() → None¶: Create a role on the Postgres cluster

drop(force: bool = False) → None¶

Drops the role connected to this object

Parameters:: force (bool) – disallow new connections and terminate all existing ones for the role before executing the drop statement

get_password_md5() → str | None¶: Returns md5 password hash for the role

refresh()¶: Re-initializes the object, refreshing its properties

script(as_composable: bool = False) → str | Composable¶

Scripts out a role.

Parameters:: as_composable (bool) – return Composable object instead of plain text
Returns:: role creation script
Return type:: Union[str, Composable]

class pgmob.objects.RoleCollection(cluster)¶

An iterable collection of roles indexed by role name.

Parameters:: cluster (str) – Postgres cluster object

cluster¶

Postgres cluster object

Type:: str

add(role: Role)¶

Adds the role object to the collection, simultaneously creating it on the cluster

Parameters:: role (Role) – initialized role object

new(name: str, password: str | None = None, superuser: bool = False, inherit: bool = True, createrole: bool = False, createdb: bool = False, login: bool = False, replication: bool = False, bypassrls: bool = False, connection_limit: int = -1, valid_until: datetime | None = None) → Role¶

Create a role object on the current Postgres cluster. The object is created ephemeral and either needs to be added to the role collection, or .create() needs to be executed.

Parameters:

name (str) – name of the role
password (str) – role password with which it will be created
superuser (bool) – SUPERUSER permissions
inherit (bool) – INHERIT permissions
createrole (bool) – CREATEROLE permissions
createdb (bool) – CREATEDB permissions
login (bool) – LOGIN permissions
replication (bool) – REPLICATION permissions
bypassrls (bool) – BYPASSRLS enabled
connection_limit (int) – Role connection limit
valid_until (datetime) – Expires on this date

refresh()¶: Resets any pending changes and retrieves objects from the cluster

Replication Slots¶

You can create, drop, and disconnect replication slots by interacting with the Replication Slot collection.

### create and delete replication slots
cluster.replication_slots.new(name='slotname', plugin='pglogical').create()
cluster.replication_slots.refresh()
cluster.replication_slots["slotname"].drop()
### working with slot collection
dir(cluster.replication_slots["myslot"])
for slot in cluster.replication_slots:
    print(slot.name, slot.is_active)
if "myslot" in cluster.replication_slots:
    cluster.replication_slots["myslot"].disconnect()

class pgmob.objects.ReplicationSlot(name: str, plugin: str, cluster: Cluster = None, parent: ReplicationSlotCollection = None)¶

Postgres ReplicationSlot object. Represents a replication slot on a Postgres server.

Parameters:

name (str) – name of the replication slot
cluster (str) – Postgres cluster object
plugin (str) – Replication slot plugin name
parent (ReplicationSlotCollection) – parent collection

name¶

Replication slot name

Type:: str

cluster¶

Postgres cluster object

Type:: str

plugin¶

Replication slot plugin name

Type:: str

slot_type¶

Replication slot type

Type:: str

database¶

Database name in which the slot is created

Type:: str

temporary¶

Whether the slot is temporary

Type:: bool

is_active¶

Whether the slot is active

Type:: bool

active_pid¶

Active PID connected to the slot

Type:: int

xmin¶

Slot xmin

Type:: str

catalog_xmin¶

Slot catalog_xmin

Type:: str

restart_lsn¶

Slot restart_lsn

Type:: str

confirmed_flush_lsn¶

Slot confirmed_flush_lsn

Type:: str

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

create() → None¶: Creates a replication slot in the currently connected database based on currently configured attributes.

disconnect()¶: Terminates the active pid of the replication slot

drop(retries: int = 10) → None¶

Drops the replication slot from the Postres cluster

Parameters:: retries (int) – number of retries after a failure. Useful when a subscriber is programmed to reconnect.

refresh()¶: Re-initializes the object, refreshing its properties

script(as_composable: bool = False) → str | Composable¶

Generate a database creation script.

Parameters:: as_composable (bool) – return Composable object instead of plain text
Returns:: replication slot creation script
Return type:: Union[str, Composable]

class pgmob.objects.ReplicationSlotCollection(cluster: Cluster)¶

An iterable collection of replication slots indexed by slot name.

add(slot: ReplicationSlot)¶

Adds the replication slot object to the collection, simultaneously creating it on the cluster

Parameters:: slot (ReplicationSlot) – initialized replication slot object

new(name: str, plugin: str) → ReplicationSlot¶

Create a replication on on the current Postgres cluster. The object is created ephemeral and either needs to be added to the slot collection, or .create() needs to be executed.

Parameters:

name (str) – name of the replication slot
cluster (str) – Postgres cluster object
plugin (str) – Replication slot plugin name
temporary (bool) – Whether the slot is temporary

refresh()¶: Resets any pending changes and retrieves objects from the cluster

Tables¶

You can perform simple maintainance operations with tables, such as renaming and changing schema and/or ownership.

dir(cluster.tables["mytable"])
for tbl in cluster.tables:
    print(tbl.name, tbl.schema)
# modify an Managed Object
tbl = cluster.tables["userschema.mytable"]
tbl.owner = "newowner"
### push changes to PostgreSQL
tbl.apply()
### refresh object attributes from server
tbl = cluster.tables["mytable"]
tbl.owner = "newowner"
tbl.refresh()  # reverts the attributes to their original values
assert tbl.owner == "oldowner"
### other methods
if "mytable" in cluster.tables:
    cluster.tables["mytable"].drop(cascade=True)

class pgmob.objects.Table(name: str, schema: str = 'public', owner: str = None, cluster: Cluster = None, parent: TableCollection = None, oid: int | None = None)¶

Postgres Table object. Represents a table object on a Postgres server.

Parameters:

name (str) – table name
cluster (str) – Postgres cluster object
schema (str) – schema name
owner (str) – table owner
oid (int) – table OID
parent (TableCollection) – parent collection

name¶

Table name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

Schema name

Type:: str

owner¶

Table owner

Type:: str

tablespace¶

Tablespace

Type:: str

row_security¶

Whether the row security is enabled

Type:: bool

oid¶

Table OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop(cascade: bool = False)¶

Drops the table from the Postgres cluster

Parameters:: cascade (bool) – drop dependent objects

refresh()¶: Re-initializes the object, refreshing its properties from Postgres cluster

class pgmob.objects.TableCollection(cluster: Cluster)¶

An iterable collection of tables indexed by table name. For tables outside of the ‘public’ schema, index becomes “schemaname.tablename”.

refresh()¶: Resets any pending changes and refreshes the list of child objects from the cluster

Views¶

You can perform simple maintainance operations with views, such as renaming and changing schema and/or ownership.

dir(cluster.views["mytable"])
for v in cluster.views:
    print(v.name, v.schema)
# modify an Managed Object
v = cluster.views["userschema.myview"]
v.owner = "newowner"
### push changes to PostgreSQL
v.apply()
### refresh object attributes from server
v = cluster.views["mytable"]
v.owner = "newowner"
v.refresh()  # reverts the attributes to their original values
assert v.owner == "oldowner"
### other methods
if "myview" in cluster.views:
    cluster.views["myview"].drop(cascade=True)

class pgmob.objects.View(name: str, schema: str = 'public', owner: str = None, cluster: Cluster = None, parent: ViewCollection = None, oid: int | None = None)¶

Postgres View object. Represents a view object on a Postgres server.

Parameters:

name (str) – name of the view
cluster (str) – Postgres cluster object
schema (str) – schema name
owner (str) – view owner
oid (int) – view OID
parent (ViewCollection) – parent collection

name¶

View name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

schema name

Type:: str

owner¶

view owner

Type:: str

oid¶

view OID

Type:: int

drop(cascade: bool = False)¶

Drops the view from the Postgres cluster

Parameters:: cascade (bool) – drop dependent objects

refresh()¶: Re-initializes the object, refreshing its properties

class pgmob.objects.ViewCollection(cluster: Cluster)¶

An iterable collection of views indexed by view name. For views outside of the ‘public’ schema, index becomes “schemaname.tablename”.

refresh()¶: Resets any pending changes and refreshes the list of child objects from the cluster

Sequences¶

dir(cluster.sequences["table_id_seq"])
### interact with sequence values
seq = cluster.sequences["table_id_seq"]
print(seq.nextval())
print(seq.currval())
seq.setval(12345)
seq.drop()

class pgmob.objects.Sequence(name: str, schema: str = 'public', owner: str = None, cluster: Cluster = None, parent: SequenceCollection = None, oid: int | None = None)¶

Postgres sequence object. Represents a sequence on a Postgres server.

Parameters:

name (str) – name of the sequence
cluster (str) – Postgres cluster object
schema (str) – Schema name
owner (str) – Sequence owner
oid (int) – Sequence OID
parent (SequenceCollection) – parent collection

name¶

Sequence name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

Schema name

Type:: str

owner¶

Sequence owner

Type:: str

data_type¶

Data type

Type:: str

start_value¶

Sequence start value

Type:: int

min_value¶

Sequence minimum value

Type:: int

max_value¶

Sequence maximum value

Type:: int

last_value¶

Sequence last value

Type:: int

increment_by¶

Increment step

Type:: int

cycle¶

Whether the sequence is allowed to cycle

Type:: bool

cache_size¶

Cache size

Type:: int

oid¶

Sequence OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

currval()¶: Retrieve the next value from the sequence

drop(cascade: bool = False)¶

Drops the sequence from the Postgres cluster

Parameters:: cascade (bool) – drop dependent objects

nextval()¶: Retrieve the next value from the sequence

refresh()¶: Re-initializes the object, refreshing its properties from Postgres cluster

setval(value: int, is_called: bool = False)¶

Set sequence’s current value and, optionally, is_called flag

Parameters:: is_called (bool) – set is_called flag

class pgmob.objects.SequenceCollection(cluster: Cluster)¶

An iterable collection of sequences indexed by sequence name. For sequences outside of the ‘public’ schema, index becomes “schemaname.sequencename”.

refresh()¶: Resets any pending changes and refreshes the list of child objects from the cluster

Procedures and Functions¶

All of the programmable objects such as Functions or Procedures are stored in the procedures attribute of the Cluster object. PostgreSQL can uniquely identify such procedures by a combination of name and its arguments. When accessing the index of a procedures attribute, we would first get a ProcedureVariations list, which, in turn, contains individual procedure objects.

dir(cluster.procedures["myfunc"][0])
for proc in [p for procvar in cluster.procedures for p in procvar]:
    print(proc.name, proc.schema)
# modify an Managed Object
proc = cluster.procedures["userschema.myproc"][0]
proc.owner = "newowner"
### push changes to PostgreSQL
proc.apply()
### refresh object attributes from PostgreSQL
proc = cluster.procedures["myproc"]
proc.owner = "newowner"
proc.refresh()  # reverts the attributes to their original values
assert proc.owner == "oldowner"
### drop the procedures
if "myfunc" in cluster.procedures:
    for pv in cluster.procedures["myfunc"]:
        pv.drop()

class pgmob.objects.Procedure(*args, **kwargs)¶

Postgres Procedure object. Represents a stored procedure on a Postgres server.

Parameters:

name (str) – name of the procedure
cluster (str) – Postgres cluster object
schema (str) – Schema name
owner (str) – Procedure owner
security_definer (bool) – Whether the procedure is a security definer
leak_proof (bool) – Whether the procedure is leak proof
strict (bool) – Whether the procedure is strict
volatility (Volatility) – Volatility mode (IMMUTABLE/STABLE/VOLATILE)
parallel_mode (ParallelSafety) – Parallel mode (SAFE/RESTRICTED/UNSAFE)
argument_types (List[str]) – A list of argument types, if any
oid (int) – Procedure OID

name¶

Procedure name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

Schema name

Type:: str

owner¶

Procedure owner

Type:: str

kind¶

Procedure kind (FUNCTION/PROCEDURE/AGGREGATE/WINDOW FUNCTION)

Type:: str

security_definer¶

Whether the function is a security definer

Type:: bool

leak_proof¶

Whether the function is leak proof

Type:: bool

strict¶

Whether the function is strict

Type:: bool

volatility¶

Volatility mode (IMMUTABLE/STABLE/VOLATILE)

Type:: Volatility

parallel_mode¶

Parallel mode (SAFE/RESTRICTED/UNSAFE)

Type:: ParallelSafety

argument_types¶

A list of argument types, if any

Type:: List[str]

oid¶

Procedure OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop(cascade: bool = False)¶

Drops the procedure from the database

Parameters:: cascade (bool) – cascade dependent objects

refresh()¶: Re-initialize the object, refreshing its properties from the database

class pgmob.objects.Function(*args, **kwargs)¶

Postgres Function object. Represents a function on a Postgres server.

Parameters:

name (str) – name of the function
cluster (str) – Postgres cluster object
schema (str) – Schema name
owner (str) – Function owner
security_definer (bool) – Whether the function is a security definer
leak_proof (bool) – Whether the function is leak proof
strict (bool) – Whether the function is strict
volatility (Volatility) – Volatility mode (IMMUTABLE/STABLE/VOLATILE)
parallel_mode (ParallelSafety) – Parallel mode (SAFE/RESTRICTED/UNSAFE)
argument_types (List[str]) – A list of argument types, if any
oid (int) – Procedure OID

name¶

Procedure name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

Schema name

Type:: str

owner¶

Procedure owner

Type:: str

security_definer¶

Whether the function is a security definer

Type:: bool

leak_proof¶

Whether the function is leak proof

Type:: bool

strict¶

Whether the function is strict

Type:: bool

volatility¶

Volatility mode (IMMUTABLE/STABLE/VOLATILE)

Type:: Volatility

parallel_mode¶

Parallel mode (SAFE/RESTRICTED/UNSAFE)

Type:: ParallelSafety

argument_types¶

A list of argument types, if any

Type:: List[str]

oid¶

Procedure OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop(cascade: bool = False)¶

Drops the procedure from the database

Parameters:: cascade (bool) – cascade dependent objects

refresh()¶: Re-initialize the object, refreshing its properties from the database

class pgmob.objects.WindowFunction(*args, **kwargs)¶

Postgres Window Function object. Represents a window function on a Postgres server.

Parameters:

name (str) – name of the function
cluster (str) – Postgres cluster object
schema (str) – Schema name
owner (str) – Function owner
security_definer (bool) – Whether the function is a security definer
leak_proof (bool) – Whether the function is leak proof
strict (bool) – Whether the function is strict
volatility (Volatility) – Volatility mode (IMMUTABLE/STABLE/VOLATILE)
parallel_mode (ParallelSafety) – Parallel mode (SAFE/RESTRICTED/UNSAFE)
argument_types (List[str]) – A list of argument types, if any
oid (int) – Procedure OID

name¶

Procedure name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

Schema name

Type:: str

owner¶

Procedure owner

Type:: str

security_definer¶

Whether the function is a security definer

Type:: bool

leak_proof¶

Whether the function is leak proof

Type:: bool

strict¶

Whether the function is strict

Type:: bool

volatility¶

Volatility mode (IMMUTABLE/STABLE/VOLATILE)

Type:: Volatility

parallel_mode¶

Parallel mode (SAFE/RESTRICTED/UNSAFE)

Type:: ParallelSafety

argument_types¶

A list of argument types, if any

Type:: List[str]

oid¶

Procedure OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop(cascade: bool = False)¶

Drops the procedure from the database

Parameters:: cascade (bool) – cascade dependent objects

refresh()¶: Re-initialize the object, refreshing its properties from the database

class pgmob.objects.Aggregate(*args, **kwargs)¶

Postgres Aggregate object. Represents an aggregate on a Postgres server.

Parameters:

name (str) – name of the aggregate function
cluster (str) – Postgres cluster object
schema (str) – Schema name
owner (str) – Function owner
security_definer (bool) – Whether the function is a security definer
leak_proof (bool) – Whether the function is leak proof
strict (bool) – Whether the function is strict
volatility (Volatility) – Volatility mode (IMMUTABLE/STABLE/VOLATILE)
parallel_mode (ParallelSafety) – Parallel mode (SAFE/RESTRICTED/UNSAFE)
argument_types (List[str]) – A list of argument types, if any
oid (int) – Procedure OID

name¶

Procedure name

Type:: str

cluster¶

Postgres cluster object

Type:: str

schema¶

Schema name

Type:: str

owner¶

Procedure owner

Type:: str

security_definer¶

Whether the function is a security definer

Type:: bool

leak_proof¶

Whether the function is leak proof

Type:: bool

strict¶

Whether the function is strict

Type:: bool

volatility¶

Volatility mode (IMMUTABLE/STABLE/VOLATILE)

Type:: Volatility

parallel_mode¶

Parallel mode (SAFE/RESTRICTED/UNSAFE)

Type:: ParallelSafety

argument_types¶

A list of argument types, if any

Type:: List[str]

oid¶

Procedure OID

Type:: int

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop(cascade: bool = False)¶

Drops the procedure from the database

Parameters:: cascade (bool) – cascade dependent objects

refresh()¶: Re-initialize the object, refreshing its properties from the database

class pgmob.objects.ProcedureVariations(cluster: Cluster)¶: A list of procedures with the same name, but variable argument sets.

class pgmob.objects.ProcedureCollection(cluster: Cluster)¶

An iterable collection of procedure variations indexed by procedure name. For procedures outside of the ‘public’ schema, index becomes “schemaname.procedurename”. Procedure variations contains all procedures with the same name, yet different set of arguments.

refresh()¶: Resets any pending changes and retrieves objects from the cluster

Large Objects¶

Large objects are indexed by their object id.

dir(cluster.large_objects)
for obj in cluster.large_objects:
    print(obj.id, obj.owner)
cluster.large_objects[123].write(b'foo')
cluster.large_objects[123].read()

class pgmob.objects.LargeObject(oid: int = None, cluster: Cluster = None, parent: LargeObjectCollection = None, owner: str = None)¶

Postgres LargeObject object. Represents a large object on a Postgres server.

Parameters:

oid (int) – LargeObject OID
cluster (str) – Postgres cluster object
definition (tuple) – definition of the largeobject; used internally

oid¶

LargeObject OID

Type:: int

cluster¶

Postgres cluster object

Type:: str

owner¶

LargeObject owner

Type:: str

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop()¶: Drops the largeobject from the Postgres cluster

read(mode='t')¶

Read Large object contents

Parameters:

mode (str) –

one of:

r: Open for read only
w: Open for write only
rw: Open for read/write
n: Don’t open the file
b: Return data as bytes
t: Decode data as string

Returns:

Large object contents

Return type:

bytes/str

refresh()¶: Re-initializes the object, refreshing its properties

truncate(len: int = 0)¶

Truncate Large object contents.

Parameters:: len (int) – truncate to this number of bytes

write(data: bytes, truncate: bool = True)¶

Overwrites Large object contents

Parameters:

data (bytes) – Large Object contents
truncate (bool) – Whether to truncate the object before write. Default = True

class pgmob.objects.LargeObjectCollection(cluster)¶

An iterable collection of largeobjects indexed by name.

refresh()¶: Resets any pending changes and retrieves objects from the cluster

Schemas¶

Database schema management.

dir(cluster.schemas)
for schema in cluster.schemas:
    print(schema.name, schema.owner)
cluster.schemas["foo"].owner = "newowner"
cluster.schemas["foo"].alter()
cluster.schemas["foo"].drop(cascade=True)

class pgmob.objects.LargeObject(oid: int = None, cluster: Cluster = None, parent: LargeObjectCollection = None, owner: str = None)¶

Postgres LargeObject object. Represents a large object on a Postgres server.

Parameters:

oid (int) – LargeObject OID
cluster (str) – Postgres cluster object
definition (tuple) – definition of the largeobject; used internally

oid¶

LargeObject OID

Type:: int

cluster¶

Postgres cluster object

Type:: str

owner¶

LargeObject owner

Type:: str

alter()¶: Alters remote object by applying local changes that were queued up for the object

property cluster: Cluster¶

Retrieves the Cluster instance bound to the object

Returns:: Postgres cluster object
Return type:: Cluster

drop()¶: Drops the largeobject from the Postgres cluster

read(mode='t')¶

Read Large object contents

Parameters:

mode (str) –

one of:

r: Open for read only
w: Open for write only
rw: Open for read/write
n: Don’t open the file
b: Return data as bytes
t: Decode data as string

Returns:

Large object contents

Return type:

bytes/str

refresh()¶: Re-initializes the object, refreshing its properties

truncate(len: int = 0)¶

Truncate Large object contents.

Parameters:: len (int) – truncate to this number of bytes

write(data: bytes, truncate: bool = True)¶

Overwrites Large object contents

Parameters:

data (bytes) – Large Object contents
truncate (bool) – Whether to truncate the object before write. Default = True

class pgmob.objects.LargeObjectCollection(cluster)¶

An iterable collection of largeobjects indexed by name.

refresh()¶: Resets any pending changes and retrieves objects from the cluster

HBA Rule collection¶

The HBA Rule collection object represents strings in the pg_hba.conf file. After modifying the rules, issue .apply() against the whole collection to save them to PostgreSQL. An old copy of the pg_hba.conf file will be stored under $PGDATA/pg_hba.conf.bak.pgm.

HBA Rules are derived from strings, which, however, would ignore whitespace when comparing one to another. This makes it convenient to modify the HBA rules using the simple syntax, similarly how you would add a list to a string array:

hba = cluster.hba_rules
print(hba)
for rule in hba:
    print(rule)
hba.append("local postgres postgres trust")
hba.remove("local    postgres   postgres   trust")
rule = "local any postgres trust"
if rule not in hba:
  hba.insert(1, rule)
### push changes to PostgreSQL
hba.apply()

class pgmob.objects.HBARule¶

A record in pg_hba.conf file. Whitespace is considered equal upon object comparison.

Parameters:: str – A line from pg_hba.conf file

property address: str | None¶: The address field

property database: str | None¶: The database field

property fields: List[str]¶: A tuple of pg_hba.conf fields extracted from the record

property type: str | None¶: The type field

property user: str | None¶: The user field

class pgmob.objects.HBARuleCollection(cluster: Cluster)¶

A collection of HBA rules in pg_hba.conf file

Parameters:

list – A list of lines from pg_hba or HBARule objects
cluster (str) – Postgres cluster object

cluster¶

Postgres cluster object

Type:: str

alter()¶: Write HBA collection back into pg_hba.conf on the Postgres server.

append(item: str | HBARule)¶

Append an HBA rule to the collection

Parameters:: item (Union[str, HBARule]) – A line from pg_hba or HBARule object

extend(item: Iterable[HBARule])¶

Add multiple HBA rules to the collection

Parameters:: item (Iterable[Any]) – An iterable of lines from pg_hba as strings or HBARule object

index(item: str | HBARule, *args) → int¶

Return a first index of a matching HBA rule from the collection

Parameters:: item (Union[str, HBARule]) – A line from pg_hba or HBARule object

insert(index: int, item: str | HBARule)¶

Insert an HBA rule into the rule collection with a certain index

Parameters:

item (Union[str, HBARule]) – A line from pg_hba or HBARule object
index (int) – Position to use

refresh()¶: Resets any pending changes and retrieves objects from the cluster

remove(item: str | HBARule)¶

Remove an HBA rule from the collection

Parameters:: item (Union[str, HBARule]) – A line from pg_hba or HBARule object

Managed Objects¶

Databases¶

Roles¶

Replication Slots¶

Tables¶

Views¶

Sequences¶

Procedures and Functions¶

Large Objects¶

Schemas¶

HBA Rule collection¶

pgmob

Navigation

Related Topics