Connection

Database connection management

This module contains the Connection class that manages the connection to the database, and the conn function that provides access to a persistent connection in datajoint.

translate_query_error

translate_query_error(client_error, query, adapter)

Translate client error to the corresponding DataJoint exception.

Parameters:

Name	Type	Description	Default
client_error	Exception	The exception raised by the client interface.	required
query	str	SQL query with placeholders.	required
adapter	DatabaseAdapter	The database adapter instance.	required

Returns:

Type	Description
Exception	An instance of the corresponding DataJoint error subclass, or the original error if no mapping exists.

conn

conn(host=None, user=None, password=None, *, init_fun=None, reset=False, use_tls=None)

Return a persistent connection object shared by multiple modules.

If the connection is not yet established or reset=True, a new connection is set up. If connection information is not provided, it is taken from config.

Parameters:

Name	Type	Description	Default
host	str	Database hostname.	None
user	str	Database username. Required if not set in config.	None
password	str	Database password. Required if not set in config.	None
init_fun	callable	Initialization function called after connection.	None
reset	bool	If True, reset existing connection. Default False.	False
use_tls	bool or dict	TLS encryption option: True (required), False (no TLS), None (preferred, default), or dict for manual configuration.	None

Returns:

Type	Description
Connection	Persistent database connection.

Raises:

Type	Description
DataJointError	If user or password is not provided and not set in config.

EmulatedCursor

acts like a cursor

Connection

Manages a connection to a database server.

Catalogues schemas, tables, and their dependencies (foreign keys). Most parameters should be set in the configuration file.

Parameters:

Name	Type	Description	Default
host	str	Hostname, may include port as hostname:port.	required
user	str	Database username.	required
password	str	Database password.	required
port	int	Port number. Overridden if specified in host.	None
init_fun	str	SQL initialization command.	None
use_tls	bool or dict	TLS encryption option.	None

Attributes:

Name	Type	Description
schemas	dict	Registered schema objects.
dependencies	Dependencies	Foreign key dependency graph.

connect

connect()

Establish or re-establish connection to the database server.

set_query_cache

set_query_cache(query_cache=None)

Enable query caching mode.

When enabled: 1. Only SELECT queries are allowed 2. Results are cached under dj.config['query_cache'] 3. Cache key differentiates cache states

Parameters:

Name	Type	Description	Default
query_cache	str	String to initialize the hash for query results. None disables caching.	None

purge_query_cache

purge_query_cache()

Delete all cached query results.

close

close()

Close the database connection.

register

register(schema)

Register a schema with this connection.

Parameters:

Name	Type	Description	Default
schema	Schema	Schema object to register.	required

ping

ping()

Ping the server to verify connection is alive.

Raises:

Type	Description
Exception	If the connection is closed.

is_connected property

is_connected

Check if connected to the database server.

Returns:

Type	Description
bool	True if connected.

query

query(query, args=(), *, as_dict=False, suppress_warnings=True, reconnect=None)

Execute a SQL query and return the cursor.

Parameters:

Name	Type	Description	Default
query	str	SQL query to execute.	required
args	tuple	Query parameters for prepared statement.	()
as_dict	bool	If True, return rows as dictionaries. Default False.	False
suppress_warnings	bool	If True, suppress SQL library warnings. Default True.	True
reconnect	bool	If True, reconnect if disconnected. None uses config setting.	None

Returns:

Type	Description
cursor	Database cursor with query results.

Raises:

Type	Description
DataJointError	If non-SELECT query during query caching mode.

get_user

get_user()

Get the current user and host.

Returns:

Type	Description
str	User name and host as 'user@host'.

in_transaction property

in_transaction

Check if a transaction is open.

Returns:

Type	Description
bool	True if a transaction is in progress.

start_transaction

start_transaction()

Start a new transaction.

Raises:

Type	Description
DataJointError	If a transaction is already in progress.

cancel_transaction

cancel_transaction()

Cancel the current transaction and roll back all changes.

commit_transaction

commit_transaction()

Commit all changes and close the transaction.

transaction property

transaction

Context manager for transactions.

Opens a transaction and automatically commits on success or rolls back on exception.

Yields:

Type	Description
Connection	This connection object.

Examples:

>>> with dj.conn().transaction:
...     # All operations here are in one transaction
...     table.insert(data)