The main entry point for dbschema is the open() function:

dbschema.open(backend, connection=None, log_sql=False, **connect_kwargs)[source]

Returns a Schema instance.

  • backend – Backend identifier, must be one of dbschema.backends.BACKEND_NAMES.
  • connection (DB-API2 connection or None) – If not None, a already opened database connection.
  • log_sql – If True SQL statements are logged (default: False).
  • connect_kwargs – Connection kwargs if not connection is given.

It is an error if both connection and connect_kwargs are given.

Returns:A Schema instance.
Raises:dbschema.exceptions.DBSchemaError if things went wrong.

Module Constants

dbschema.BACKEND_MYSQL = 'mysql'

Identifier for MySQL databases.

dbschema.BACKEND_POSTGRESQL = 'postgresql'

Identifier for PostgreSQL databases.

dbschema.BACKEND_SQLITE3 = 'sqlite3'

Identifier for SQLite3 databases.


The following exceptions are defined in dbschema.exceptions:

exception dbschema.exceptions.DBSchemaError[source]

Base class for all exceptions in this module.

exception dbschema.exceptions.DBSchemaOperationError[source]

Used when a database operation fails.

Variables:orignal_exc – Contains the original exception raised by the underlying DB-API2 module.

Database Objects

The following graph illustrates the class inheritance in this module:

Inheritance diagram of dbschema.objects

The following representations of database objects are defined in dbschema.objects:

class dbschema.objects.Node(name, **kwargs)[source]

Base class for database objects.

name = None

The name of the object.

description = None

The description of the object.

oid = None

A unique identifier provided by the underlying backend.


Adds a child objects.

find(type_cls=None, name=None, parent=None, recurse=True, **kwargs)[source]

Yields database objects matching search parameters.

All search parameters are optional. If not parameters are given all database objects are returned.

  • type_cls (Subclass of Node) – Find specific types.
  • name (str) – The name to match.
  • parent (Instance of Node) – The parent of the objects that should be yieled.
  • kwargs – All other keyword parameters are used to compare with the attributes of the child instances.
  • recurse – If True (the default) recurse into children.

Iterator of Node instances.


Returns exact one match or None.

For parameter reference see find().


Returns a set of child types for this node.

class dbschema.objects.Database(name)[source]

Central database class.

set_connection(connection, **connect_kwargs)[source]

Sets the connection to interact with the database.

  • connection – If not None, a already opened database connection. :type connection: DB-API2 connection or None
  • connect_kwargs – Connection kwargs if not connection is given.

It is an error if both connection and connect_kwargs are given.


Returns version information of the database.

Return type:str

Returns the default namespace or None.

Return type:Namespace or None

Yields all tables from default namespace.

Return type:Generator of Table instances.

Yields all views from the default namespace.

Return type:Generator of View instances-
set_dirty(type_cls, dirty)[source]

Marks/unmarks a certain type as dirty.

  • type_cls – A Node subclass.
  • dirty (bool) – Wether the type is dirty.

Instructs the backend to refresh certain types.

“type_clss” is a list of dbschema.objects.Node classes that should be refreshed.

class dbschema.objects.Namespace(name, **kwargs)[source]

A namespace/schema in the database.


Returns True if this namespace is a default namespace.

class dbschema.objects.Table(name, **kwargs)[source]

A table in the database.


Yields columns of this table.

Return type:Generator of Column instances.

Yields foreign key definitions.

Return type:Generator of ForeignKey instances.

Yields foreign keys pointing to this table.

Return type:Generaotr of ForeignKey instances.
class dbschema.objects.View(name, **kwargs)[source]

A view in the database.


Yields columns of this view.

class dbschema.objects.Column(name, **kwargs)[source]

A column of a view or table.

class dbschema.objects.ForeignKey(*args, **kwargs)[source]

A foreign key definition of a table.