Global Attributes & Functions Overview

The mssql_python module provides a set of global attributes and functions that are accessible across all connections and cursors created using mssql_python. These features are designed to work consistently, regardless of the specific connection or cursor instance, ensuring a unified experience when interacting with Microsoft SQL Server through Python.

Global Attributes (Read-Only)

Attribute	Value	Description
apilevel	"2.0"	The DB API level supported (per PEP 249).
paramstyle	"pyformat"	The default parameter style used in SQL queries. Supports both pyformat (%(name)s) and qmark (?) styles with automatic detection.
threadsafety	1	Indicates that threads may share the module but not connections.
lowercase	False	If True, column names returned from queries are automatically converted to lowercase.
decimal_separator	"." (default)	The character used when parsing NUMERIC/DECIMAL values. Initialized at import from locale, defaults to "." if unavailable.

Parameter Styles

The mssql_python module supports two parameter styles for SQL queries:

Style	Placeholder	Example	Parameters
pyformat (default)	%(name)s	SELECT * FROM T WHERE id = %(id)s	{"id": 1}
qmark	?	SELECT * FROM T WHERE id = ?	(1,) or [1]

The driver automatically detects which style is being used and converts as needed. This means you can use either style without any configuration changes:

import mssql_python

conn = mssql_python.connect(conn_str)
cursor = conn.cursor()

# Using pyformat style (default) with dictionary parameters
cursor.execute(
    "SELECT * FROM users WHERE name = %(name)s AND age > %(age)s",
    {"name": "Alice", "age": 25}
)

# Using qmark style with tuple/list parameters
cursor.execute(
    "SELECT * FROM users WHERE name = ? AND age > ?",
    ("Alice", 25)
)

Note: Both styles work interchangeably. The driver handles the conversion internally, ensuring backward compatibility with existing qmark-style code while enabling the more readable pyformat style.

Functions

get_settings()

Returns the global settings object.

import mssql_python

settings = mssql_python.get_settings()
print(settings.lowercase)         # False
print(settings.decimal_separator) # "."

setDecimalSeparator(separator)

Sets the decimal separator character used when parsing NUMERIC/DECIMAL values.

Args

• separator (str): Must be a single non-whitespace, non-control character string.

Raises

• ValueError: If the input is empty, longer than one character, whitespace, or a control character.

import mssql_python

# Change separator to comma
mssql_python.setDecimalSeparator(",")

getDecimalSeparator()

Returns the current decimal separator.

import mssql_python

sep = mssql_python.getDecimalSeparator()
print(sep)   # "."

pooling(max_size=100, idle_timeout=600, enabled=True)

Configures the connection pooling behavior.

Args

• max_size (int): Maximum number of connections in the pool.
• idle_timeout (int): Seconds before idle connections are closed.
• enabled (bool): Enable (True) or disable (False) pooling.

import mssql_python

# Enable pooling with defaults
mssql_python.pooling()

# Enable pooling with custom values
mssql_python.pooling(max_size=50, idle_timeout=300)

# Disable pooling
mssql_python.pooling(enabled=False)

⚠️ Security & Usage Notes

• Be careful when changing the decimal separator: setting it incorrectly may cause numeric parsing issues or inconsistent behavior across environments.
• When enabling connection pooling, ensure proper sizing of max_size and idle_timeout to avoid resource exhaustion or stale connections in long-running applications.