Connection Parameters

General SQLAlchemy Engine Parameters

The table below lists parameters used in the Connection Specification.

Parameter	Description
drivername	The name of the database backend. For SQLAlchemy-Exasol, this is "exa+websocket".
username	The name of the user for authentication, e.g. "sys".
password	The password associated with the given username. This should not be encoded, and special characters do not need to be escaped, e.g. "exasol".
host	The host data source name (DSN) to access the database, e.g. "127.0.0.1".
port	The port number to access the database, e.g. 8563.
query	A dictionary of string keys to string values to be passed to the dialect upon connecting, e.g. {"AUTOCOMMIT": "y"}. For other relevant keywords, see Specific URL Query Parameters for SQLAlchemy-Exasol.
connect_args	A dictionary of options supported by the PyExasol WebSocket DBAPI, passed to create_engine. fetch_mapper: Available since PyExasol 3.0.0. Use this callable to customize the mapping of returned database values to Python types; it receives (value, data_type). See the custom fetch mapper example and PyExasol Compatibility and Value Conversion.

Specific URL Query Parameters for SQLAlchemy-Exasol

The table below lists URL query parameters supported by the SQLAlchemy-Exasol dialect. Add them to the URL query string or the query dictionary passed to URL.create; their values are supplied as strings and converted by the dialect as needed.

Keyword	Description
AUTOCOMMIT	This indicates if the connection automatically commits or not. The parsed value is case-insensitive. (default) To enable autocommit, specify "y" or "yes". To disable autocommit, specify "n" or "no".
ENCRYPTION	This indicates if the connection should be encrypted or not. The parsed value is case-insensitive. (default) To enable TLS encryption, specify "y" or "yes". To disable TLS encryption (not recommended), specify "n" or "no". For more information about TLS encryption, please see Transport Layer Security (TLS).
FINGERPRINT	An alternate to SSL certificate verification is to verify the connection via a fingerprint. (default) Fingerprint verification is not active. To use fingerprint verification, provide your fingerprint value (e.g. "0ACD07D4E9CEEB122773A71B9C3BD01CE49FC99901DE7C0E0030C942805BA64C"). For more information about fingerprint verification, please see Fingerprint Verification.
SSLCertificate	This indicates if the connection should verify the SSL certificate or not. (default) SSL certificate verification is active. There is currently not an option for users to directly specify this as enabled. To disable SSL certificate verification (NOT recommended and NOT secure), specify "SSL_VERIFY_NONE". This value is case-insensitive. For more information about verifying the SSL certificate, please see About Certificate Verification.

PyExasol Compatibility and Value Conversion

SQLAlchemy-Exasol uses the WebSocket DBAPI provided by PyExasol. PyExasol 3.0.0 changed the default WebSocket DBAPI conversion so that values are converted to Python types as early as possible, in accordance with PEP 249.

The following table describes values exposed by SQLAlchemy-Exasol through the WebSocket DBAPI. The PyExasol version columns show the version-dependent behavior seen by SQLAlchemy-Exasol; None is returned for NULL values for all types.

Exasol type	SQLAlchemy-Exasol with PyExasol < 3.0.0	SQLAlchemy-Exasol with PyExasol >= 3.0.0
BOOLEAN	bool	bool
CHAR	str	str
DATE	datetime.date	datetime.date
DECIMAL(p, 0)	int [1]	int
DECIMAL(p, s) where s > 0	decimal.Decimal [1]	decimal.Decimal
DOUBLE	float	float
GEOMETRY	str	str
HASHTYPE	metadata KeyError (str)	str
INTERVAL DAY TO SECOND	str	ExaTimeDelta
INTERVAL YEAR TO MONTH	str	str
TIMESTAMP	datetime.datetime [1]	datetime.datetime
TIMESTAMP WITH LOCAL TIME ZONE	str	datetime.datetime
VARCHAR	str	str

[1] (1,2,3)

PyExasol versions before 3.0.0 returned strings for these types, and SQLAlchemy-Exasol converted those strings to the displayed Python types.

The SQLAlchemy column type declaration can change the Python type returned. With PyExasol >= 3.0.0, a native Exasol DECIMAL(p, 0) value is returned as int. If the column is instead declared with SQLAlchemy’s Numeric(18, 0) type, SQLAlchemy applies its decimal result processor and returns decimal.Decimal.

For release-specific conversion details and the complete list of changes, see the PyExasol 3.0.0 release notes.

Custom fetch mapper

Applications can provide their own PyExasol fetch_mapper through SQLAlchemy’s connect_args. The mapper receives (value, data_type) for each fetched value, as described in PyExasol’s DBAPI documentation. It replaces PyExasol’s default mapper, so applications must handle the value types they need. See the custom fetch mapper example.