RPC API¶

Mathesar has an API available at /api/rpc/v0/ which follows the JSON-RPC spec version 2.0.

Not yet stable

The RPC API is not yet stable and may change in the future. If you build logic that depends on this API, be mindful that it may change in the future without warning or notice.

Usage¶

Requests¶

To use an RPC function:

Call it with a dot path starting from its root path.
Always use named parameters.
Ensure that your request includes HTTP headers for valid session IDs, as well as CSRF cookies and tokens.

Example

To call function add_from_known_connection from the connections section of this page, you’d send something like:

POST /api/rpc/v0/b

{
  "jsonrpc": "2.0",
  "id": 234,
  "method": "connections.add_from_known_connection",
  "params": {
    "nickname": "anewconnection",
    "db_name": "mynewcooldb"
  },
}

Responses¶

Success¶

Upon a successful call to an RPC function, the API will return a success object. Such an object has the following form:

{
  "jsonrpc": "2.0",
  "id": 234,
  "result": <any>
}

The result is whatever was returned by the underlying function.

Errors¶

When an error is produced by a call to the RPC endpoint, we produce an error of the following form:

{
  "jsonrpc": "2.0",
  "id": 234,
  "error": {
    "code": <int>,
    "message": <str>
  }
}

The code is a negative integer. Some codes are produced according to the JSON-RPC spec.

Other error codes are grouped according to the library that produced the Exception:

builtins: -31xxx
psycopg or psycopg2: -30xxx
django: -29xxx
mathesar (our code): -28xxx
db (our code): -27xxx
sqlalchemy: -26xxx
other: -25xxx

Unrecognized errors from a given library return a “round number” code, so an unknown builtins error gets the code -31000.

Collaborators¶

collaborators.list_ ¶

list_(*, database_id=None, **kwargs)

List information about collaborators. Exposed as list.

If called with no database_id, all collaborators for all databases are listed.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database associated with the collaborators.	`None`

Returns:

Type	Description
`list[CollaboratorInfo]`	A list of collaborators.

collaborators.add ¶

add(*, database_id, user_id, configured_role_id, **kwargs)

Set up a new collaborator for a database.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the Database to associate with the collaborator.	required
`user_id`	`int`	The Django id of the User model instance who’d be the collaborator.	required
`configured_role_id`	`int`	The Django id of the ConfiguredRole model instance to associate with the collaborator.	required

collaborators.delete ¶

delete(*, collaborator_id, **kwargs)

Delete a collaborator from a database.

Parameters:

Name	Type	Description	Default
`collaborator_id`	`int`	The Django id of the UserDatabaseRoleMap model instance of the collaborator.	required

collaborators.set_role ¶

set_role(*, collaborator_id, configured_role_id, **kwargs)

Set the role of a collaborator for a database.

Parameters:

Name	Type	Description	Default
`collaborator_id`	`int`	The Django id of the UserDatabaseRoleMap model instance of the collaborator.	required
`configured_role_id`	`int`	The Django id of the ConfiguredRole model instance to associate with the collaborator.	required

collaborators.CollaboratorInfo ¶

Bases: TypedDict

Information about a collaborator.

Attributes:

Name	Type	Description
`id`	`int`	the Django ID of the UserDatabaseRoleMap model instance.
`user_id`	`int`	The Django ID of the User model instance of the collaborator.
`database_id`	`int`	the Django ID of the Database model instance for the collaborator.
`configured_role_id`	`int`	The Django ID of the ConfiguredRole model instance for the collaborator.

Columns¶

columns.list_ ¶

list_(*, table_oid, database_id, **kwargs)

List information about columns for a table. Exposed as list.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[ColumnInfo]`	A list of column details.

columns.add ¶

add(*, column_data_list, table_oid, database_id, **kwargs)

Add columns to a table.

There are defaults for both the name and type of a column, and so passing [{}] for column_data_list would add a single column of type CHARACTER VARYING, with an auto-generated name.

Parameters:

Name	Type	Description	Default
`column_data_list`	`list[CreatableColumnInfo]`	A list describing desired columns to add.	required
`table_oid`	`int`	Identity of the table to which we’ll add columns.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[int]`	An array of the attnums of the new columns.

columns.patch ¶

patch(
    *, column_data_list, table_oid, database_id, **kwargs
)

Alter details of preexisting columns in a table.

Does not support altering the type or type options of array columns.

Parameters:

Name	Type	Description	Default
`column_data_list`	`list[SettableColumnInfo]`	A list describing desired column alterations.	required
`table_oid`	`int`	Identity of the table whose columns we’ll modify.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`int`	The number of columns altered.

columns.delete ¶

delete(*, column_attnums, table_oid, database_id, **kwargs)

Delete columns from a table.

Parameters:

Name	Type	Description	Default
`column_attnums`	`list[int]`	A list of attnums of columns to delete.	required
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`int`	The number of columns dropped.

columns.list_with_metadata ¶

list_with_metadata(*, table_oid, database_id, **kwargs)

List information about columns for a table, along with the metadata associated with each column. Args: table_oid: Identity of the table in the user’s database. database_id: The Django id of the database containing the table. Returns: A list of column details.

columns.ColumnInfo ¶

Bases: TypedDict

Information about a column. Extends the settable fields.

Attributes:

Name	Type	Description
`id`	`int`	The `attnum` of the column in the table.
`name`	`str`	The name of the column.
`type`	`str`	The type of the column on the database.
`type_options`	`TypeOptions`	The options applied to the column type.
`nullable`	`bool`	Whether or not the column is nullable.
`primary_key`	`bool`	Whether the column is in the primary key.
`default`	`ColumnDefault`	The default value and whether it’s dynamic.
`has_dependents`	`bool`	Whether the column has dependent objects.
`description`	`str`	The description of the column.
`current_role_priv`	`list[Literal['SELECT', 'INSERT', 'UPDATE', 'REFERENCES']]`	The privileges available to the user for the column.
`valid_target_types`	`list[str]`	A list of all types to which the column can be cast.

columns.CreatableColumnInfo ¶

Bases: TypedDict

Information needed to add a new column.

No keys are required.

Attributes:

Name	Type	Description
`name`	`Optional[str]`	The name of the column.
`type`	`Optional[str]`	The type of the column on the database.
`type_options`	`Optional[TypeOptions]`	The options applied to the column type.
`nullable`	`Optional[bool]`	Whether or not the column is nullable.
`default`	`Optional[ColumnDefault]`	The default value.
`description`	`Optional[str]`	The description of the column.

columns.PreviewableColumnInfo ¶

Bases: TypedDict

Information needed to preview a column.

Attributes:

Name	Type	Description
`id`	`int`	The `attnum` of the column in the table.
`type`	`Optional[str]`	The new type to be applied to a column.
`type_options`	`Optional[TypeOptions]`	The options to be applied to the column type.

columns.SettableColumnInfo ¶

Bases: TypedDict

Information about a column, restricted to settable fields.

When possible, Passing null for a key will clear the underlying setting. E.g.,

default = null clears the column default setting.
type_options = null clears the type options for the column.
description = null clears the column description.

Setting any of name, type, or nullable is a noop.

Only the id key is required.

Attributes:

Name	Type	Description
`id`	`int`	The `attnum` of the column in the table.
`name`	`Optional[str]`	The name of the column.
`type`	`Optional[str]`	The type of the column on the database.
`type_options`	`Optional[TypeOptions]`	The options applied to the column type.
`nullable`	`Optional[bool]`	Whether or not the column is nullable.
`default`	`Optional[ColumnDefault]`	The default value.
`description`	`Optional[str]`	The description of the column.

columns.TypeOptions ¶

Bases: TypedDict

Options applied to a type. All attributes are optional.

Take special care with the difference between numeric and date/time types w.r.t. precision. The attribute has a different meaning depending on the type to which it’s being applied.

Attributes:

Name	Type	Description
`precision`	`int`	For numeric types, the number of significant digits. For date/time types, the number of fractional digits.
`scale`	`int`	For numeric types, the number of fractional digits.
`fields`	`str`	Which time fields are stored. See Postgres docs.
`length`	`int`	The maximum length of a character-type field.
`item_type`	`str`	The member type for arrays.

columns.ColumnDefault ¶

Bases: TypedDict

A dictionary describing the default value for a column.

Attributes:

Name	Type	Description
`value`	`str`	An SQL expression giving the default value.
`is_dynamic`	`bool`	Whether the `value` is possibly dynamic.

Column Metadata¶

Classes and functions exposed to the RPC endpoint for managing column metadata.

columns.metadata.list_ ¶

list_(*, table_oid, database_id, **kwargs)

List metadata associated with columns for a table. Exposed as list.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[ColumnMetaDataRecord]`	A list of column meta data objects.

columns.metadata.set_ ¶

set_(
    *,
    column_meta_data_list,
    table_oid,
    database_id,
    **kwargs
)

Set metadata associated with columns of a table for a database. Exposed as set.

Parameters:

Name	Type	Description	Default
`column_meta_data_list`	`list[ColumnMetaDataBlob]`	A list describing desired metadata alterations.	required
`table_oid`	`int`	Identity of the table whose metadata we’ll modify.	required
`database_id`	`int`	The Django id of the database containing the table.	required

columns.metadata.ColumnMetaDataRecord ¶

Bases: TypedDict

Metadata for a column in a table.

Only the database, table_oid, and attnum keys are required.

Attributes:

Name	Type	Description
`database_id`	`int`	The Django id of the database containing the table.
`table_oid`	`int`	The OID of the table containing the column.
`attnum`	`int`	The attnum of the column in the table.
`bool_input`	`Optional[Literal['dropdown', 'checkbox']]`	How the input for a boolean column should be shown.
`bool_true`	`Optional[str]`	A string to display for `true` values.
`bool_false`	`Optional[str]`	A string to display for `false` values.
`num_min_frac_digits`	`Optional[int]`	Minimum digits shown after the decimal point.
`num_max_frac_digits`	`Optional[int]`	Maximum digits shown after the decimal point.
`num_grouping`	`Optional[str]`	Specifies how grouping separators are displayed for numeric values.
`num_format`	`Optional[str]`	Specifies the locale-specific format for displaying numeric values.
`mon_currency_symbol`	`Optional[str]`	The currency symbol shown for money value.
`mon_currency_location`	`Optional[Literal['after-minus', 'end-with-space']]`	Where the currency symbol should be shown.
`time_format`	`Optional[str]`	A string representing the format of time values.
`date_format`	`Optional[str]`	A string representing the format of date values.
`duration_min`	`Optional[str]`	The smallest unit for displaying durations.
`duration_max`	`Optional[str]`	The largest unit for displaying durations.

columns.metadata.ColumnMetaDataBlob ¶

Bases: TypedDict

The metadata fields which can be set for a column in a table.

Attributes:

Name	Type	Description
`attnum`	`int`	The attnum of the column in the table.
`bool_input`	`Optional[Literal['dropdown', 'checkbox']]`	How the input for a boolean column should be shown.
`bool_true`	`Optional[str]`	A string to display for `true` values.
`bool_false`	`Optional[str]`	A string to display for `false` values.
`num_min_frac_digits`	`Optional[int]`	Minimum digits shown after the decimal point.
`num_max_frac_digits`	`Optional[int]`	Maximum digits shown after the decimal point.
`num_grouping`	`Optional[str]`	Specifies how grouping separators are displayed for numeric values.
`num_format`	`Optional[str]`	Specifies the locale-specific format for displaying numeric values.
`mon_currency_symbol`	`Optional[str]`	The currency symbol shown for money value.
`mon_currency_location`	`Optional[Literal['after-minus', 'end-with-space']]`	Where the currency symbol should be shown.
`time_format`	`Optional[str]`	A string representing the format of time values.
`date_format`	`Optional[str]`	A string representing the format of date values.
`duration_min`	`Optional[str]`	The smallest unit for displaying durations.
`duration_max`	`Optional[str]`	The largest unit for displaying durations.

Configured Databases¶

databases.configured.list_ ¶

list_(*, server_id=None, **kwargs)

List information about databases for a server. Exposed as list.

If called with no server_id, all databases for all servers are listed.

Parameters:

Name	Type	Description	Default
`server_id`	`int`	The Django id of the server containing the databases.	`None`

Returns:

Type	Description
`list[ConfiguredDatabaseInfo]`	A list of database details.

databases.configured.disconnect ¶

disconnect(*, database_id, **kwargs)

Disconnect a configured database.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database.	required

databases.configured.ConfiguredDatabaseInfo ¶

Bases: TypedDict

Information about a database.

Attributes:

Name	Type	Description
`id`	`int`	the Django ID of the database model instance.
`name`	`str`	The name of the database on the server.
`server_id`	`int`	the Django ID of the server model instance for the database.

Connections¶

Classes and functions exposed to the RPC endpoint for creating connections.

connections.add_from_known_connection ¶

add_from_known_connection(
    *,
    nickname,
    database,
    create_db=False,
    connection_id=None,
    sample_data=[]
)

Add a new connection from an already existing one.

If no connection_id is passed, the internal database connection will be used.

Parameters:

Name	Type	Description	Default
`nickname`	`str`	Identify the added connection. Should be unique.	required
`database`	`str`	The name of the database on the server.	required
`create_db`	`bool`	Whether we should create the database `database` if it doesn’t already exist.	`False`
`connection_id`	`int`	Identifies the known connection when combined with the user_database value for the connection_type parameter	`None`
`sample_data`	`list[str]`	A list of strings requesting that some example data sets be installed on the underlying database. Valid list members are ‘library_management’ and ‘movie_collection’.	`[]`

Returns:

Type	Description
`ConnectionReturn`	Metadata about the Database associated with the connection.

connections.add_from_scratch ¶

add_from_scratch(
    *,
    nickname,
    database,
    user,
    password,
    host,
    port,
    sample_data=[]
)

Add a new connection to a PostgreSQL server from scratch.

This requires inputting valid credentials for the connection. When setting up the connection, therefore, the database must already exist on the PostgreSQL server.

Parameters:

Name	Type	Description	Default
`nickname`	`str`	Identify the added connection. Should be unique.	required
`database`	`str`	The name of the database on the server.	required
`user`	`str`	A valid user (role) on the server, with `CONNECT` and `CREATE` privileges on the database given by `database`.	required
`password`	`str`	The password for `user`.	required
`host`	`str`	The hostname or IP address of the PostgreSQL server.	required
`port`	`int`	The port of the PostgreSQL server.	required
`sample_data`	`list[str]`	A list of strings requesting that some example data sets be installed on the underlying database. Valid list members are ‘library_management’ and ‘movie_collection’.	`[]`

Returns:

Type	Description
`ConnectionReturn`	Metadata about the Database associated with the connection.

connections.grant_access_to_user ¶

grant_access_to_user(*, connection_id, user_id)

Migrate a connection to new models and grant access to a user.

This function is designed to be temporary, and should probably be removed once we have completed the new users and permissions setup for beta. You pass any conneciton id and user id. The function will fill the required models as needed.

Parameters:

Name	Type	Description	Default
`connection_id`	`int`	The Django id of an old-style connection.	required
`user_id`	`int`	The Django id of a user.	required

connections.ConnectionReturn ¶

Bases: TypedDict

Information about a connection model.

Attributes:

Name	Type	Description
`id`	`int`	The Django id of the Connection object added.
`nickname`	`str`	Used to identify the added connection.
`database`	`str`	The name of the database on the server.
`username`	`str`	The username of the role for the connection.
`host`	`str`	The hostname or IP address of the Postgres server.
`port`	`int`	The port of the Postgres server.

Constraints¶

Classes and functions exposed to the RPC endpoint for managing table constraints.

constraints.list_ ¶

list_(*, table_oid, database_id, **kwargs)

List information about constraints in a table. Exposed as list.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	The oid of the table to list constraints for.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[ConstraintInfo]`	A list of constraint details.

constraints.add ¶

add(
    *, table_oid, constraint_def_list, database_id, **kwargs
)

Add constraint(s) on a table in bulk.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table to delete constraint for.	required
`constraint_def_list`	`CreatableConstraintInfo`	A list describing the constraints to add.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[int]`	The oid(s) of all the constraints on the table.

constraints.delete ¶

delete(*, table_oid, constraint_oid, database_id, **kwargs)

Delete a constraint from a table.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table to delete constraint for.	required
`constraint_oid`	`int`	The OID of the constraint to delete.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`str`	The name of the dropped constraint.

constraints.ForeignKeyConstraint ¶

Bases: TypedDict

Information about a foreign key constraint.

Attributes:

Name	Type	Description
`type`	`str`	The type of the constraint(`'f'` for foreign key constraint).
`columns`	`list[int]`	List of columns to set a foreign key on.
`fkey_relation_id`	`int`	The OID of the referent table.
`fkey_columns`	`list[int]`	List of referent column(s).
`name`	`Optional[str]`	The name of the constraint.
`deferrable`	`Optional[bool]`	Whether to postpone constraint checking until the end of the transaction.
`fkey_update_action`	`Optional[str]`	Specifies what action should be taken when the referenced key is updated. Valid options include `'a'(no action)`(default behavior), `'r'(restrict)`, `'c'(cascade)`, `'n'(set null)`, `'d'(set default)`
`fkey_delete_action`	`Optional[str]`	Specifies what action should be taken when the referenced key is deleted. Valid options include `'a'(no action)`(default behavior), `'r'(restrict)`, `'c'(cascade)`, `'n'(set null)`, `'d'(set default)`
`fkey_match_type`	`Optional[str]`	Specifies how the foreign key matching should be performed. Valid options include `'f'(full match)`, `'s'(simple match)`(default behavior).

constraints.PrimaryKeyConstraint ¶

Bases: TypedDict

Information about a primary key constraint.

Attributes:

Name	Type	Description
`type`	`str`	The type of the constraint(`'p'` for primary key constraint).
`columns`	`list[int]`	List of columns to set a primary key on.
`name`	`Optional[str]`	The name of the constraint.
`deferrable`	`Optional[bool]`	Whether to postpone constraint checking until the end of the transaction.

constraints.UniqueConstraint ¶

Bases: TypedDict

Information about a unique constraint.

Attributes:

Name	Type	Description
`type`	`str`	The type of the constraint(`'u'` for unique constraint).
`columns`	`list[int]`	List of columns to set a unique constraint on.
`name`	`Optional[str]`	The name of the constraint.
`deferrable`	`Optional[bool]`	Whether to postpone constraint checking until the end of the transaction.

constraints.CreatableConstraintInfo `module-attribute` ¶

CreatableConstraintInfo = list[
    Union[
        ForeignKeyConstraint,
        PrimaryKeyConstraint,
        UniqueConstraint,
    ]
]

Type alias for a list of createable constraints which can be unique, primary key, or foreign key constraints.

Data Modeling¶

Classes and functions exposed to the RPC endpoint for managing data models.

data_modeling.add_foreign_key_column ¶

add_foreign_key_column(
    *,
    column_name,
    referrer_table_oid,
    referent_table_oid,
    database_id,
    **kwargs
)

Add a foreign key column to a table.

The foreign key column will be newly created, and will reference the id column of the referent table.

Parameters:

Name	Type	Description	Default
`column_name`	`str`	The name of the column to create.	required
`referrer_table_oid`	`int`	The OID of the table getting the new column.	required
`referent_table_oid`	`int`	The OID of the table being referenced.	required

data_modeling.add_mapping_table ¶

add_mapping_table(
    *,
    table_name,
    mapping_columns,
    schema_oid,
    database_id,
    **kwargs
)

Add a mapping table to give a many-to-many link between referents.

The foreign key columns in the mapping table will reference the id column of the referent tables.

Parameters:

Name	Type	Description	Default
`table_name`	`str`	The name for the new mapping table.	required
`schema_oid`	`int`	The OID of the schema for the mapping table.	required
`mapping_columns`	`list[MappingColumn]`	The foreign key columns to create in the mapping table.	required

data_modeling.suggest_types ¶

suggest_types(*, table_oid, database_id, **kwargs)

Infer the best type for each column in the table.

Currently we only suggest different types for columns which originate as type text.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	The OID of the table whose columns we’re inferring types for.	required
`database_id`	`int`	The Django id of the database containing the table.	required

The response JSON will have attnum keys, and values will be the result of format_type for the inferred type of each column, i.e., the canonical string referring to the type.

data_modeling.split_table ¶

split_table(
    *,
    table_oid,
    column_attnums,
    extracted_table_name,
    database_id,
    relationship_fk_column_name=None,
    **kwargs
)

Extract columns from a table to create a new table, linked by a foreign key.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	The OID of the table whose columns we’ll extract.	required
`column_attnums`	`list`	A list of the attnums of the columns to extract.	required
`extracted_table_name`	`str`	The name of the new table to be made from the extracted columns.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`relationship_fk_column_name`	`str`	The name to give the new foreign key column in the remainder table (optional)	`None`

Returns:

Type	Description
`SplitTableInfo`	The SplitTableInfo object describing the details for the created table as a result of column extraction.

data_modeling.move_columns ¶

move_columns(
    *,
    source_table_oid,
    target_table_oid,
    move_column_attnums,
    database_id,
    **kwargs
)

Extract columns from a table to a referent table, linked by a foreign key.

Parameters:

Name	Type	Description	Default
`source_table_oid`	`int`	The OID of the source table whose column(s) we’ll extract.	required
`target_table_oid`	`int`	The OID of the target table where the extracted column(s) will be added.	required
`move_column_attnums`	`list[int]`	The list of attnum(s) to move from source table to the target table.	required
`database_id`	`int`	The Django id of the database containing the table.	required

data_modeling.MappingColumn ¶

Bases: TypedDict

An object defining a foreign key column in a mapping table.

Attributes:

Name	Type	Description
`column_name`	`str`	The name of the foreign key column.
`referent_table_oid`	`int`	The OID of the table the column references.

data_modeling.SplitTableInfo ¶

Bases: TypedDict

Information about a table, created from column extraction.

Attributes:

Name	Type	Description
`extracted_table_oid`	`int`	The OID of the table that is created from column extraction.
`new_fkey_attnum`	`int`	The attnum of the newly created foreign key column referring the extracted_table on the original table.

Databases¶

databases.get ¶

get(*, database_id, **kwargs)

Get information about a database.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database.	required

Returns:

Type	Description
`DatabaseInfo`	Information about the database, and the current user privileges.

databases.delete ¶

delete(*, database_oid, database_id, **kwargs)

Drop a database from the server.

Parameters:

Name	Type	Description	Default
`database_oid`	`int`	The OID of the database to delete on the database.	required
`database_id`	`int`	The Django id of the database to connect to.	required

databases.DatabaseInfo ¶

Bases: TypedDict

Information about a database current user privileges on it.

Attributes:

Name	Type	Description
`oid`	`int`	The `oid` of the database on the server.
`name`	`str`	The name of the database on the server.
`owner_oid`	`int`	The `oid` of the owner of the database.
`current_role_priv`	`list[Literal['CONNECT', 'CREATE', 'TEMPORARY']]`	A list of privileges available to the user.
`current_role_owns`	`bool`	Whether the user is an owner of the database.

Database Privileges¶

databases.privileges.list_direct ¶

list_direct(*, database_id, **kwargs)

List database privileges for non-inherited roles.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database.	required

Returns:

Type	Description
`list[DBPrivileges]`	A list of database privileges.

databases.privileges.replace_for_roles ¶

replace_for_roles(*, privileges, database_id, **kwargs)

Replace direct database privileges for roles.

Possible privileges are CONNECT, CREATE, and TEMPORARY.

Only roles which are included in a passed DBPrivileges object are affected.

WARNING: Any privilege included in the direct list for a role is GRANTed, and any privilege not included is REVOKEd.

Attributes:

Name	Type	Description
`privileges`		The new privilege sets for roles.
`database_id`		The Django id of the database.

Returns:

Type	Description
`list[DBPrivileges]`	A list of all non-default privileges on the database after the
`list[DBPrivileges]`	operation.

databases.privileges.transfer_ownership ¶

transfer_ownership(*, new_owner_oid, database_id, **kwargs)

Transfers ownership of the current database to a new owner.

Attributes:

Name	Type	Description
`new_owner_oid`		The OID of the role whom we want to be the new owner of the current database.
`database_id`		The Django id of the database whose ownership is to be transferred.

To successfully transfer ownership of a database to a new owner the current user must:

Be a Superuser/Owner of the current database.
Be a MEMBER of the new owning role. i.e. The current role should be able to SET ROLE to the new owning role.
Have CREATEDB privilege.

Returns:

Type	Description
`DatabaseInfo`	Information about the database, and the current user privileges.

databases.privileges.DBPrivileges ¶

Bases: TypedDict

Information about database privileges.

Attributes:

Name	Type	Description
`role_oid`	`int`	The `oid` of the role on the database server.
`direct`	`list[Literal['CONNECT', 'CREATE', 'TEMPORARY']]`	A list of database privileges for the afforementioned role_oid.

Database Setup¶

RPC functions for setting up database connections.

databases.setup.create_new ¶

create_new(*, database, sample_data=[], **kwargs)

Set up a new database on the internal server.

The calling user will get access to that database using the default role stored in Django settings.

Parameters:

Name	Type	Description	Default
`database`	`str`	The name of the new database.	required
`sample_data`	`list[str]`	A list of strings requesting that some example data sets be installed on the underlying database. Valid list members are ‘library_management’ and ‘movie_collection’.	`[]`

databases.setup.connect_existing ¶

connect_existing(
    *,
    host,
    port,
    database,
    role,
    password,
    sample_data=[],
    **kwargs
)

Connect Mathesar to an existing database on a server.

The calling user will get access to that database using the credentials passed to this function.

Parameters:

Name	Type	Description	Default
`host`	`str`	The host of the database server.	required
`port`	`int`	The port of the database server.	required
`database`	`str`	The name of the database on the server.	required
`role`	`str`	The role on the server to use for the connection.	required
`password`	`str`	A password valid for the role.	required
`sample_data`	`list[str]`	A list of strings requesting that some example data sets be installed on the underlying database. Valid list members are ‘library_management’ and ‘movie_collection’.	`[]`

databases.setup.DatabaseConnectionResult ¶

Bases: TypedDict

Info about the objects resulting from calling the setup functions.

These functions will get or create an instance of the Server, Database, and ConfiguredRole models, as well as a UserDatabaseRoleMap entry.

Attributes:

Name	Type	Description
`server`	`ConfiguredServerInfo`	Information on the Server model instance.
`database`	`ConfiguredDatabaseInfo`	Information on the Database model instance.
`configured_role`	`ConfiguredRoleInfo`	Information on the ConfiguredRole model instance.

Explorations¶

Classes and functions exposed to the RPC endpoint for managing explorations.

explorations.list_ ¶

list_(*, database_id, schema_oid=None, **kwargs)

List information about explorations for a database. Exposed as list.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database containing the explorations.	required
`schema_oid`	`int`	The OID of the schema containing the base table(s) of the exploration(s).(optional)	`None`

Returns:

Type	Description
`list[ExplorationInfo]`	A list of exploration details.

explorations.get ¶

get(*, exploration_id, **kwargs)

List information about an exploration.

Parameters:

Name	Type	Description	Default
`exploration_id`	`int`	The Django id of the exploration.	required

Returns:

Type	Description
`ExplorationInfo`	Exploration details for a given exploration_id.

explorations.add ¶

add(*, exploration_def)

Add a new exploration.

Parameters:

Name	Type	Description	Default
`exploration_def`	`ExplorationDef`	A dict describing the exploration to create.	required

Returns:

Type	Description
`ExplorationInfo`	The exploration details for the newly created exploration.

explorations.delete ¶

delete(*, exploration_id, **kwargs)

Delete an exploration.

Parameters:

Name	Type	Description	Default
`exploration_id`	`int`	The Django id of the exploration to delete.	required

explorations.replace ¶

replace(*, new_exploration)

Replace a saved exploration.

Parameters:

Name	Type	Description	Default
`new_exploration`	`ExplorationInfo`	A dict describing the exploration to replace, including the updated fields.	required

Returns:

Type	Description
`ExplorationInfo`	The exploration details for the replaced exploration.

explorations.run ¶

run(*, exploration_def, limit=100, offset=0, **kwargs)

Run an exploration.

Parameters:

Name	Type	Description	Default
`exploration_def`	`ExplorationDef`	A dict describing an exploration to run.	required
`limit`	`int`	The max number of rows to return.(default 100)	`100`
`offset`	`int`	The number of rows to skip.(default 0)	`0`

Returns:

Type	Description
`ExplorationResult`	The result of the exploration run.

explorations.run_saved ¶

run_saved(*, exploration_id, limit=100, offset=0, **kwargs)

Run a saved exploration.

Parameters:

Name	Type	Description	Default
`exploration_id`	`int`	The Django id of the exploration to run.	required
`limit`	`int`	The max number of rows to return.(default 100)	`100`
`offset`	`int`	The number of rows to skip.(default 0)	`0`

Returns:

Type	Description
`ExplorationResult`	The result of the exploration run.

explorations.ExplorationInfo ¶

Bases: TypedDict

Information about an exploration.

Attributes:

Name	Type	Description
`id`	`int`	The Django id of an exploration.
`database_id`	`int`	The Django id of the database containing the exploration.
`name`	`str`	The name of the exploration.
`base_table_oid`	`int`	The OID of the base table of the exploration on the database.
`schema_oid`	`int`	The OID of the schema containing the base table of the exploration.
`initial_columns`	`list`	A list describing the columns to be included in the exploration.
`transformations`	`Optional[list]`	A list describing the transformations to be made on the included columns.
`display_options`	`Optional[list]`	A list describing metadata for the columns in the explorations.
`display_names`	`Optional[dict]`	A map between the actual column names on the database and the alias to be displayed(if any).
`description`	`Optional[str]`	The description of the exploration.

explorations.ExplorationDef ¶

Bases: TypedDict

Definition about a runnable exploration.

Attributes:

Name	Type	Description
`database_id`	`int`	The Django id of the database containing the exploration.
`name`	`str`	The name of the exploration.
`base_table_oid`	`int`	The OID of the base table of the exploration on the database.
`schema_oid`	`int`	The OID of the schema containing the base table of the exploration.
`initial_columns`	`list`	A list describing the columns to be included in the exploration.
`transformations`	`Optional[list]`	A list describing the transformations to be made on the included columns.
`display_options`	`Optional[list]`	A list describing metadata for the columns in the explorations.
`display_names`	`Optional[dict]`	A map between the actual column names on the database and the alias to be displayed(if any).
`description`	`Optional[str]`	The description of the exploration.

explorations.ExplorationResult ¶

Bases: TypedDict

Result of an exploration run.

Attributes:

Name	Type	Description
`query`	`dict`	A dict describing the exploration that ran.
`records`	`dict`	A dict describing the total count of records along with the contents of those records.
`output_columns`	`tuple`	A tuple describing the names of the columns included in the exploration.
`column_metadata`	`dict`	A dict describing the metadata applied to included columns.
`limit`	`Optional[int]`	Specifies the max number of rows returned.(default 100)
`offset`	`Optional[int]`	Specifies the number of rows skipped.(default 0)
`filter`	`Optional[dict]`	A dict describing filters applied to an exploration.
`order_by`	`Optional[list[dict]]`	The ordering applied to the columns of an exploration.
`search`	`Optional[list[dict]]`	Specifies a list of dicts containing column names and searched expression.
`duplicate_only`	`Optional[list]`	A list of column names for which you want duplicate records.

Records¶

Classes and functions exposed to the RPC endpoint for managing table records.

records.list_ ¶

list_(
    *,
    table_oid,
    database_id,
    limit=None,
    offset=None,
    order=None,
    filter=None,
    grouping=None,
    return_record_summaries=False,
    **kwargs
)

List records from a table, and its row count. Exposed as list.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`limit`	`int`	The maximum number of rows we’ll return.	`None`
`offset`	`int`	The number of rows to skip before returning records from following rows.	`None`
`order`	`list[OrderBy]`	An array of ordering definition objects.	`None`
`filter`	`Filter`	An array of filter definition objects.	`None`
`grouping`	`Grouping`	An array of group definition objects.	`None`
`return_record_summaries`	`bool`	Whether to return summaries of retrieved records.	`False`

Returns:

Type	Description
`RecordList`	The requested records, along with some metadata.

records.get ¶

get(
    *,
    record_id,
    table_oid,
    database_id,
    return_record_summaries=False,
    **kwargs
)

Get single record from a table by its primary key.

Parameters:

Name	Type	Description	Default
`record_id`	`Any`	The primary key value of the record to be gotten.	required
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`return_record_summaries`	`bool`	Whether to return summaries of the retrieved record.	`False`

Returns:

Type	Description
`RecordList`	The requested record, along with some metadata.

records.add ¶

add(
    *,
    record_def,
    table_oid,
    database_id,
    return_record_summaries=False,
    **kwargs
)

Add a single record to a table.

The form of the record_def is determined by the underlying table. Keys should be attnums, and values should be the desired value for that column in the created record. Missing keys will use default values (if set on the DB), and explicit null values will set null for that value regardless of default (with obvious exceptions where that would violate some constraint)

Parameters:

Name	Type	Description	Default
`record_def`	`dict`	An object representing the record to be added.	required
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`return_record_summaries`	`bool`	Whether to return summaries of the added record.	`False`

Returns:

Type	Description
`RecordAdded`	The created record, along with some metadata.

records.patch ¶

patch(
    *,
    record_def,
    record_id,
    table_oid,
    database_id,
    return_record_summaries=False,
    **kwargs
)

Modify a record in a table.

The form of the record_def is determined by the underlying table. Keys should be attnums, and values should be the desired value for that column in the modified record. Explicit null values will set null for that value (with obvious exceptions where that would violate some constraint).

Parameters:

Name	Type	Description	Default
`record_def`	`dict`	An object representing the record to be added.	required
`record_id`	`Any`	The primary key value of the record to modify.	required
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`return_record_summaries`	`bool`	Whether to return summaries of the modified record.	`False`

Returns:

Type	Description
`RecordAdded`	The modified record, along with some metadata.

records.delete ¶

delete(*, record_ids, table_oid, database_id, **kwargs)

Delete records from a table by primary key.

Parameters:

Name	Type	Description	Default
`record_ids`	`list[Any]`	The primary key values of the records to be deleted.	required
`table_oid`	`int`	The identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`Optional[int]`	The number of records deleted.

records.search ¶

search(
    *,
    table_oid,
    database_id,
    search_params=[],
    limit=10,
    return_record_summaries=False,
    **kwargs
)

List records from a table according to search_params.

Literals will be searched for in a basic way in string-like columns, but will have to match exactly in non-string-like columns.

Records are assigned a score based on how many matches, and of what quality, they have with the passed search parameters.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`search_params`	`list[SearchParam]`	Results are ranked and filtered according to the objects passed here.	`[]`
`limit`	`int`	The maximum number of rows we’ll return.	`10`

Returns:

Type	Description
`RecordList`	The requested records, along with some metadata.

records.RecordList ¶

Bases: TypedDict

Records from a table, along with some meta data

The form of the objects in the results array is determined by the underlying records being listed. The keys of each object are the attnums of the retrieved columns. The values are the value for the given row, for the given column.

Attributes:

Name	Type	Description
`count`	`int`	The total number of records in the table.
`results`	`list[dict]`	An array of record objects.
`grouping`	`GroupingResponse`	Information for displaying grouped records.
`linked_record_smmaries`	`GroupingResponse`	Information for previewing foreign key values, provides a map of foreign key to a text summary.
`record_summaries`	`dict[str, str]`	Information for previewing returned records.

records.RecordAdded ¶

Bases: TypedDict

Record from a table, along with some meta data

The form of the object in the results array is determined by the underlying records being listed. The keys of each object are the attnums of the retrieved columns. The values are the value for the given row, for the given column.

Attributes:

Name	Type	Description
`results`	`list[dict]`	An array of a single record objects (the one added).
`linked_record_summaries`	`dict[str, dict[str, str]]`	Information for previewing foreign key values, provides a map of foreign key to a text summary.
`record_summaries`	`dict[str, str]`	Information for previewing an added record.

records.OrderBy ¶

Bases: TypedDict

An object defining an ORDER BY clause.

Attributes:

Name	Type	Description
`attnum`	`int`	The attnum of the column to order by.
`direction`	`Literal['asc', 'desc']`	The direction to order by.

records.Filter ¶

Bases: TypedDict

An object defining a filter to be used in a WHERE clause.

For valid type values, see the msar.filter_templates table defined in mathesar/db/sql/00_msar.sql.

Attributes:

Name	Type	Description
`type`	`str`	a function or operator to be used in filtering.
`args`	`list[Union[Filter, FilterAttnum, FilterLiteral]]`	The ordered arguments for the function or operator.

records.FilterAttnum ¶

Bases: TypedDict

An object choosing a column for a filter.

Attributes:

Name	Type	Description
`type`	`Literal['attnum']`	Must be `"attnum"`
`value`	`int`	The attnum of the column to filter by

records.FilterLiteral ¶

Bases: TypedDict

An object defining a literal for an argument to a filter.

Attributes:

Name	Type	Description
`type`	`Literal['literal']`	must be `"literal"`.
`value`	`Any`	The value of the literal.

records.Grouping ¶

Bases: TypedDict

Grouping definition.

The table involved must have a single column primary key.

Attributes:

Name	Type	Description
`columns`	`list[int]`	The columns to be grouped by.
`preproc`	`list[str]`	The preprocessing funtions to apply (if any).

records.Group ¶

Bases: TypedDict

Group definition.

Note that the count is over all rows in the group, whether returned or not. However, result_indices is restricted to only the rows returned. This is to avoid potential problems if there are many rows in the group (e.g., the whole table), but we only return a few.

Attributes:

Name	Type	Description
`id`	`int`	The id of the group. Consistent for same input.
`count`	`int`	The number of items in the group.
`results_eq`	`list[dict]`	The value the results of the group equal.
`result_indices`	`list[int]`	The 0-indexed positions of group members in the results array.

records.GroupingResponse ¶

Bases: TypedDict

Grouping response object. Extends Grouping with actual groups.

Attributes:

Name	Type	Description
`columns`	`list[int]`	The columns to be grouped by.
`preproc`	`list[str]`	The preprocessing funtions to apply (if any).
`groups`	`list[Group]`	The groups applicable to the records being returned.

records.SearchParam ¶

Bases: TypedDict

Search definition for a single column.

Attributes:

Name	Type	Description
`attnum`	`int`	The attnum of the column in the table.
`literal`	`Any`	The literal to search for in the column.

Roles¶

roles.list_ ¶

list_(*, database_id, **kwargs)

List information about roles for a database server. Exposed as list. Requires a database id inorder to connect to the server.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database.	required

Returns:

Type	Description
`list[RoleInfo]`	A list of roles present on the database server.

roles.add ¶

add(
    *,
    rolename,
    database_id,
    password=None,
    login=None,
    **kwargs
)

Add a new login/non-login role on a database server.

Parameters:

Name	Type	Description	Default
`rolename`	`str`	The name of the role to be created.	required
`database_id`	`int`	The Django id of the database.	required
`password`	`str`	The password for the rolename to set.	`None`
`login`	`bool`	Whether the role to be created could login.	`None`

Returns:

Type	Description
`RoleInfo`	A dict describing the created role.

roles.delete ¶

delete(*, role_oid, database_id, **kwargs)

Drop a role on a database server.

Parameters:

Name	Type	Description	Default
`role_oid`	`int`	The OID of the role to drop on the database.	required
`database_id`	`int`	The Django id of the database.	required

roles.get_current_role ¶

get_current_role(*, database_id, **kwargs)

Get information about the current role and all the parent role(s) whose privileges are immediately available to current role without doing SET ROLE.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database.	required

Returns:

Type	Description
`dict`	A dict describing the current role.

roles.set_members ¶

set_members(
    *, parent_role_oid, members, database_id, **kwargs
)

Grant/Revoke direct membership to/from roles.

Parameters:

Name	Type	Description	Default
`parent_role_oid`	`int`	The OID of role whose membership will be granted/revoked to/from other roles.	required
`members`	`list`	An array of role OID(s) whom we want to grant direct membership of the parent role. Only the OID(s) present in the array will be granted membership of parent role, Membership will be revoked for existing members not present in this array.	required

Returns:

Type	Description
`RoleInfo`	A dict describing the updated information of the parent role.

roles.RoleInfo ¶

Bases: TypedDict

Information about a role.

Attributes:

Name	Type	Description
`oid`	`int`	The OID of the role.
`name`	`str`	Name of the role.
`super`	`bool`	Whether the role has SUPERUSER status.
`inherits`	`bool`	Whether the role has INHERIT attribute.
`create_role`	`bool`	Whether the role has CREATEROLE attribute.
`create_db`	`bool`	Whether the role has CREATEDB attribute.
`login`	`bool`	Whether the role has LOGIN attribute.
`description`	`Optional[str]`	A description of the role
`members`	`Optional[list[RoleMember]]`	The member roles that directly inherit the role.

Refer PostgreSQL documenation on

roles.RoleMember ¶

Bases: TypedDict

Information about a member role of a directly inherited role.

Attributes:

Name	Type	Description
`oid`	`int`	The OID of the member role.
`admin`	`bool`	Whether the member role has ADMIN option on the inherited role.

Roles Configured¶

roles.configured.list_ ¶

list_(*, server_id, **kwargs)

List information about roles configured in Mathesar. Exposed as list.

Parameters:

Name	Type	Description	Default
`server_id`	`int`	The Django id of the Server containing the configured roles.	required

Returns:

Type	Description
`list[ConfiguredRoleInfo]`	A list of configured roles.

roles.configured.add ¶

add(*, server_id, name, password, **kwargs)

Configure a role in Mathesar for a database server.

Parameters:

Name	Type	Description	Default
`server_id`	`int`	The Django id of the Server to contain the configured role.	required
`name`	`str`	The name of the role.	required
`password`	`str`	The password for the role.	required

Returns:

Type	Description
`ConfiguredRoleInfo`	The newly configured role.

roles.configured.delete ¶

delete(*, configured_role_id, **kwargs)

Delete a configured role for a server.

Parameters:

Name	Type	Description	Default
`configured_role_id`	`int`	The Django id of the ConfiguredRole model instance.	required

roles.configured.set_password ¶

set_password(*, configured_role_id, password, **kwargs)

Set the password of a configured role for a server.

Parameters:

Name	Type	Description	Default
`configured_role_id`	`int`	The Django id of the ConfiguredRole model instance.	required
`password`	`str`	The password for the role.	required

roles.configured.ConfiguredRoleInfo ¶

Bases: TypedDict

Information about a role configured in Mathesar.

Attributes:

Name	Type	Description
`id`	`int`	the Django ID of the ConfiguredRole model instance.
`name`	`str`	The name of the role.
`server_id`	`int`	The Django ID of the Server model instance for the role.

Schemas¶

schemas.list_ ¶

list_(*, database_id, **kwargs)

List information about schemas in a database. Exposed as list.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[SchemaInfo]`	A list of SchemaInfo objects

schemas.get ¶

get(*, schema_oid, database_id, **kwargs)

Get information about a schema in a database.

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	The OID of the schema to get.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`SchemaInfo`	The SchemaInfo describing the user-defined schema in the database.

schemas.add ¶

add(
    *,
    name,
    database_id,
    owner_oid=None,
    description=None,
    **kwargs
)

Add a schema

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the schema to add.	required
`database_id`	`int`	The Django id of the database containing the schema.	required
`owner_oid`	`int`	The OID of the role who will own the new schema. If owner_oid is None, the current role will be the owner of the new schema.	`None`
`description`	`Optional[str]`	A description of the schema	`None`

Returns:

Type	Description
`SchemaInfo`	The SchemaInfo describing the user-defined schema in the database.

schemas.delete ¶

delete(*, schema_oid, database_id, **kwargs)

Delete a schema, given its OID.

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	The OID of the schema to delete.	required
`database_id`	`int`	The Django id of the database containing the schema.	required

schemas.patch ¶

patch(*, schema_oid, database_id, patch, **kwargs)

Patch a schema, given its OID.

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	The OID of the schema to delete.	required
`database_id`	`int`	The Django id of the database containing the schema.	required
`patch`	`SchemaPatch`	A SchemaPatch object containing the fields to update.	required

Returns:

Type	Description
`SchemaInfo`	The SchemaInfo describing the user-defined schema in the database.

schemas.SchemaInfo ¶

Bases: TypedDict

Information about a schema

Attributes:

Name	Type	Description
`oid`	`int`	The OID of the schema
`name`	`str`	The name of the schema
`description`	`Optional[str]`	A description of the schema
`owner_oid`	`int`	The OID of the owner of the schema
`current_role_priv`	`list[Literal['USAGE', 'CREATE']]`	All privileges available to the calling role on the schema.
`current_role_owns`	`bool`	Whether the current role is the owner of the schema (even indirectly).
`table_count`	`int`	The number of tables in the schema

schemas.SchemaPatch ¶

Bases: TypedDict

Attributes:

Name	Type	Description
`name`	`Optional[str]`	The name of the schema
`description`	`Optional[str]`	A description of the schema

Schema Privileges¶

schemas.privileges.list_direct ¶

list_direct(*, schema_oid, database_id, **kwargs)

List direct schema privileges for roles.

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	The OID of the schema whose privileges we’ll list.	required
`database_id`	`int`	The Django id of the database containing the schema.	required

Returns:

Type	Description
`list[SchemaPrivileges]`	A list of schema privileges.

schemas.privileges.replace_for_roles ¶

replace_for_roles(
    *, privileges, schema_oid, database_id, **kwargs
)

Replace direct schema privileges for roles.

Possible privileges are USAGE and CREATE.

Only roles which are included in a passed SchemaPrivileges object are affected.

WARNING: Any privilege included in the direct list for a role is GRANTed, and any privilege not included is REVOKEd.

Parameters:

Name	Type	Description	Default
`privileges`	`list[SchemaPrivileges]`	The new privilege sets for roles.	required
`schema_oid`	`int`	The OID of the affected schema.	required
`database_id`	`int`	The Django id of the database containing the schema.	required

Returns:

Type	Description
`list[SchemaPrivileges]`	A list of all non-default privileges on the schema after the
`list[SchemaPrivileges]`	operation.

schemas.privileges.transfer_ownership ¶

transfer_ownership(
    *, schema_oid, new_owner_oid, database_id, **kwargs
)

Transfers ownership of a given schema to a new owner.

Attributes:

Name	Type	Description
`schema_oid`		The OID of the schema to transfer.
`new_owner_oid`		The OID of the role whom we want to be the new owner of the schema.

To successfully transfer ownership of a schema to a new owner the current user must:

Be a Superuser/Owner of the schema.
Be a MEMBER of the new owning role. i.e. The current role should be able to SET ROLE to the new owning role.
Have CREATE privilege for the database.

Returns:

Type	Description
`SchemaInfo`	Information about the schema, and the current user privileges.

schemas.privileges.SchemaPrivileges ¶

Bases: TypedDict

Information about schema privileges for a role.

Attributes:

Name	Type	Description
`role_oid`	`int`	The `oid` of the role.
`direct`	`list[Literal['USAGE', 'CREATE']]`	A list of schema privileges for the afforementioned role_oid.

Servers¶

Tables¶

tables.list_ ¶

list_(*, schema_oid, database_id, **kwargs)

List information about tables for a schema. Exposed as list.

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	Identity of the schema in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[TableInfo]`	A list of table details.

tables.get ¶

get(*, table_oid, database_id, **kwargs)

List information about a table for a schema.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`TableInfo`	Table details for a given table oid.

tables.add ¶

add(
    *,
    schema_oid,
    database_id,
    table_name=None,
    column_data_list=[],
    constraint_data_list=[],
    owner_oid=None,
    comment=None,
    **kwargs
)

Add a table with a default id column.

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	Identity of the schema in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`table_name`	`str`	Name of the table to be created.	`None`
`column_data_list`	`list[CreatableColumnInfo]`	A list describing columns to be created for the new table, in order.	`[]`
`constraint_data_list`	`list[CreatableConstraintInfo]`	A list describing constraints to be created for the new table.	`[]`
`owner_oid`	`int`	The OID of the role who will own the new table. If owner_oid is None, the current role will be the owner of the new table.	`None`
`comment`	`str`	The comment for the new table.	`None`

Returns:

Type	Description
`AddedTableInfo`	The `oid` & `name` of the created table.

tables.delete ¶

delete(*, table_oid, database_id, cascade=False, **kwargs)

Delete a table from a schema.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`cascade`	`bool`	Whether to drop the dependent objects.	`False`

Returns:

Type	Description
`str`	The name of the dropped table.

tables.patch ¶

patch(*, table_oid, table_data_dict, database_id, **kwargs)

Alter details of a preexisting table in a database.

Parameters:

Name	Type	Description	Default
`table_oid`	`str`	Identity of the table whose name, description or columns we’ll modify.	required
`table_data_dict`	`SettableTableInfo`	A list describing desired table alterations.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`str`	The name of the altered table.

tables.import_ ¶

import_(
    *,
    data_file_id,
    schema_oid,
    database_id,
    table_name=None,
    comment=None,
    **kwargs
)

Import a CSV/TSV into a table.

Parameters:

Name	Type	Description	Default
`data_file_id`	`int`	The Django id of the DataFile containing desired CSV/TSV.	required
`schema_oid`	`int`	Identity of the schema in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`table_name`	`str`	Name of the table to be imported.	`None`
`comment`	`str`	The comment for the new table.	`None`

Returns:

Type	Description
`AddedTableInfo`	The `oid` and `name` of the created table.

tables.get_import_preview ¶

get_import_preview(
    *, table_oid, columns, database_id, limit=20, **kwargs
)

Preview an imported table.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the imported table in the user’s database.	required
`columns`	`list[PreviewableColumnInfo]`	List of settings describing the casts to be applied to the columns.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`limit`	`int`	The upper limit for the number of records to return.	`20`

Returns:

Type	Description
`list[dict]`	The records from the specified columns of the table.

tables.list_joinable ¶

list_joinable(
    *, table_oid, database_id, max_depth=3, **kwargs
)

List details for joinable tables.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	Identity of the table to get joinable tables for.	required
`database_id`	`int`	The Django id of the database containing the table.	required
`max_depth`	`int`	Specifies how far to search for joinable tables.	`3`

Returns:

Type	Description
`JoinableTableInfo`	Joinable table details for a given table.

tables.list_with_metadata ¶

list_with_metadata(*, schema_oid, database_id, **kwargs)

List tables in a schema, along with the metadata associated with each table

Parameters:

Name	Type	Description	Default
`schema_oid`	`int`	PostgreSQL OID of the schema containing the tables.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list`	A list of table details along with metadata.

tables.get_with_metadata ¶

get_with_metadata(*, table_oid, database_id, **kwargs)

Get information about a table in a schema, along with the associated table metadata.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	The OID of the table in the user’s database.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`dict`	A dict describing table details along with its metadata.

tables.TableInfo ¶

Bases: TypedDict

Information about a table.

Attributes:

Name	Type	Description
`oid`	`int`	The `oid` of the table in the schema.
`name`	`str`	The name of the table.
`schema`	`int`	The `oid` of the schema where the table lives.
`description`	`Optional[str]`	The description of the table.
`owner_oid`	`int`	The OID of the direct owner of the table.
`current_role_priv`	`list[Literal['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES', 'TRIGGER']]`	The privileges available to the user on the table.
`current_role_owns`	`bool`	Whether the current role owns the table.

tables.AddedTableInfo ¶

Bases: TypedDict

Information about a newly created table.

Attributes:

Name	Type	Description
`oid`	`int`	The `oid` of the table in the schema.
`name`	`str`	The name of the table.

tables.SettableTableInfo ¶

Bases: TypedDict

Information about a table, restricted to settable fields.

When possible, Passing null for a key will clear the underlying setting. E.g.,

description = null clears the table description.

Setting any of name, columns to null is a noop.

Attributes:

Name	Type	Description
`name`	`Optional[str]`	The new name of the table.
`description`	`Optional[str]`	The description of the table.
`columns`	`Optional[list[SettableColumnInfo]]`	A list describing desired column alterations.

tables.JoinableTableRecord ¶

Bases: TypedDict

Information about a singular joinable table.

Attributes:

Name	Type	Description
`base`	`int`	The OID of the table from which the paths start
`target`	`int`	The OID of the table where the paths end.
`join_path`	`list`	A list describing joinable paths in the following form: [ [[L_oid0, L_attnum0], [R_oid0, R_attnum0]], [[L_oid1, L_attnum1], [R_oid1, R_attnum1]], [[L_oid2, L_attnum2], [R_oid2, R_attnum2]], … ] Here, [L_oidN, L_attnumN] represents the left column of a join, and [R_oidN, R_attnumN] the right.
`fkey_path`	`list`	Same as `join_path` expressed in terms of foreign key constraints in the following form: [ [constraint_id0, reversed], [constraint_id1, reversed], ] In this form, `constraint_idN` is a foreign key constraint, and `reversed` is a boolean giving whether to travel from referrer to referant (when False) or from referant to referrer (when True).
`depth`	`int`	Specifies how far to search for joinable tables.
`multiple_results`	`bool`	Specifies whether the path included is reversed.

tables.JoinableTableInfo ¶

Bases: TypedDict

Information about joinable table(s).

Attributes:

Name	Type	Description
`joinable_tables`	`list[JoinableTableRecord]`	List of reachable joinable table(s) from a base table.
`target_table_info`	`list`	Additional info about target table(s) and its column(s).

Table Metadata¶

Classes and functions exposed to the RPC endpoint for managing table metadata.

tables.metadata.list_ ¶

list_(*, database_id, **kwargs)

List metadata associated with tables for a database.

Parameters:

Name	Type	Description	Default
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[TableMetaDataRecord]`	Metadata object for a given table oid.

tables.metadata.set_ ¶

set_(*, table_oid, metadata, database_id, **kwargs)

Set metadata for a table.

Parameters:

Name	Type	Description	Default
`table_oid`	`int`	The PostgreSQL OID of the table.	required
`metadata`	`TableMetaDataBlob`	A TableMetaDataBlob object describing desired table metadata to set.	required
`database_id`	`int`	The Django id of the database containing the table.	required

tables.metadata.TableMetaDataBlob ¶

Bases: TypedDict

The metadata fields which can be set on a table

Attributes:

Name	Type	Description
`data_file_id`	`Optional[int]`	Specifies the DataFile model id used for the import.
`import_verified`	`Optional[bool]`	Specifies whether a file has been successfully imported into a table.
`column_order`	`Optional[list[int]]`	The order in which columns of a table are displayed.
`record_summary_customized`	`Optional[bool]`	Specifies whether the record summary has been customized.
`record_summary_template`	`Optional[str]`	Record summary template for a referent column.

tables.metadata.TableMetaDataRecord ¶

Bases: TypedDict

Metadata for a table in a database.

Only the database and table_oid keys are required.

Attributes:

Name	Type	Description
`id`	`int`	The Django id of the TableMetaData object.
`database_id`	`int`	The Django id of the database containing the table.
`table_oid`	`int`	The OID of the table in the database.
`data_file_id`	`Optional[int]`	Specifies the DataFile model id used for the import.
`import_verified`	`Optional[bool]`	Specifies whether a file has been successfully imported into a table.
`column_order`	`Optional[list[int]]`	The order in which columns of a table are displayed.
`record_summary_customized`	`Optional[bool]`	Specifies whether the record summary has been customized.
`record_summary_template`	`Optional[str]`	Record summary template for a referent column.

Table Privileges¶

tables.privileges.list_direct ¶

list_direct(*, table_oid, database_id, **kwargs)

List direct table privileges for roles. Args: table_oid: The OID of the table whose privileges we’ll list. database_id: The Django id of the database containing the table. Returns: A list of table privileges.

tables.privileges.replace_for_roles ¶

replace_for_roles(
    *, privileges, table_oid, database_id, **kwargs
)

Replace direct table privileges for roles.

Possible privileges are INSERT, SELECT, UPDATE, DELETE, TRUNCATE, REFERENCES and TRIGGER.

Only roles which are included in a passed TablePrivileges object are affected.

WARNING: Any privilege included in the direct list for a role is GRANTed, and any privilege not included is REVOKEd.

Parameters:

Name	Type	Description	Default
`privileges`	`list[TablePrivileges]`	The new privilege sets for roles.	required
`table_oid`	`int`	The OID of the affected table.	required
`database_id`	`int`	The Django id of the database containing the table.	required

Returns:

Type	Description
`list[TablePrivileges]`	A list of all non-default privileges on the table after the
`list[TablePrivileges]`	operation.

tables.privileges.transfer_ownership ¶

transfer_ownership(
    *, table_oid, new_owner_oid, database_id, **kwargs
)

Transfers ownership of a given table to a new owner.

Attributes:

Name	Type	Description
`table_oid`		The OID of the table to transfer.
`new_owner_oid`		The OID of the role whom we want to be the new owner of the table.

To successfully transfer ownership of a table to a new owner the current user must:

Be a Superuser/Owner of the table.
Be a MEMBER of the new owning role. i.e. The current role should be able to SET ROLE to the new owning role.
Have CREATE privilege on the table’s schema.

Returns:

Type	Description
`TableInfo`	Information about the table, and the current user privileges.

tables.privileges.TablePrivileges ¶

Bases: TypedDict

Information about table privileges for a role. Attributes: role_oid: The oid of the role. direct: A list of table privileges for the afforementioned role_oid.

Types¶

Classes and functions exposed to the RPC endpoint for listing types in a database.

types.list_ ¶

list_()

List information about types available on the database. Exposed as list.

types.TypeInfo ¶

Bases: TypedDict

Information about a type.

Attributes:

Name	Type	Description
`identifier`	`str`	Specifies the type class that db_type(s) belongs to.
`name`	`str`	Specifies the UI name for a type class.
`db_types`	`list`	Specifies the name(s) of types present on the database.
`display_options`	`Optional[dict]`	Specifies metadata related to a type class.

RPC API¶

Usage¶

Requests¶

Responses¶

Success¶

Errors¶

Collaborators¶

collaborators.list_ ¶

collaborators.add ¶

collaborators.delete ¶

collaborators.set_role ¶

collaborators.CollaboratorInfo ¶

Columns¶

columns.list_ ¶

columns.add ¶

columns.patch ¶

columns.delete ¶

columns.list_with_metadata ¶

columns.ColumnInfo ¶

columns.CreatableColumnInfo ¶

columns.PreviewableColumnInfo ¶

columns.SettableColumnInfo ¶

columns.TypeOptions ¶

columns.ColumnDefault ¶

Column Metadata¶

columns.metadata.list_ ¶

columns.metadata.set_ ¶

columns.metadata.ColumnMetaDataRecord ¶

columns.metadata.ColumnMetaDataBlob ¶

Configured Databases¶

databases.configured.list_ ¶

databases.configured.disconnect ¶

databases.configured.ConfiguredDatabaseInfo ¶

Connections¶

connections.add_from_known_connection ¶

connections.add_from_scratch ¶

connections.grant_access_to_user ¶

connections.ConnectionReturn ¶

Constraints¶

constraints.list_ ¶

constraints.add ¶

constraints.delete ¶

constraints.ForeignKeyConstraint ¶

constraints.PrimaryKeyConstraint ¶

constraints.UniqueConstraint ¶

constraints.CreatableConstraintInfo module-attribute ¶

Data Modeling¶

data_modeling.add_foreign_key_column ¶

data_modeling.add_mapping_table ¶

data_modeling.suggest_types ¶

data_modeling.split_table ¶

data_modeling.move_columns ¶

data_modeling.MappingColumn ¶

data_modeling.SplitTableInfo ¶

Databases¶

databases.get ¶

databases.delete ¶

databases.DatabaseInfo ¶

Database Privileges¶

databases.privileges.list_direct ¶

databases.privileges.replace_for_roles ¶

databases.privileges.transfer_ownership ¶

databases.privileges.DBPrivileges ¶

Database Setup¶

databases.setup.create_new ¶

databases.setup.connect_existing ¶

databases.setup.DatabaseConnectionResult ¶

Explorations¶

explorations.list_ ¶

explorations.get ¶

explorations.add ¶

explorations.delete ¶

explorations.replace ¶

explorations.run ¶

explorations.run_saved ¶

explorations.ExplorationInfo ¶

explorations.ExplorationDef ¶

explorations.ExplorationResult ¶

Records¶

records.list_ ¶

constraints.CreatableConstraintInfo `module-attribute` ¶