Script Development / SQL Construction DFF.SQL

DFF.SQL(...) is used to construct parameterized SQL, avoiding inserting user input via string concatenation. Most SQL connectors already have this capability built in, and you can directly call conn.query(sql, sql_params=...) or conn.non_query(...).

Only when you need to explicitly format SQL for debugging, or when the caller must receive the final SQL string, do you need to call DFF.SQL(...) separately.

Parameters and Placeholders

Parameter	Type	Required / Default	Description
sql	str	Required	SQL statement containing parameter placeholders
sql_params	list	None	SQL parameters provided in placeholder order

Placeholder	Meaning	Example result
?	Value parameter, escaped and quoted	'user-001'
??	Identifier or SQL fragment, not quoted	users

sql = DFF.SQL(
    'SELECT * FROM ?? WHERE id = ?',
    ['users', 'user-001'],
)
# SELECT * FROM users WHERE id = 'user-001'

?? does not protect untrusted input

User input must be placed in ?. Identifiers such as table names and field names can be placed in ?? only if they come from an allowlist or trusted configuration. Do not insert SQL values via f-strings or string concatenation.

Parameter Expansion

Array parameters are automatically expanded into multiple values, and two-dimensional arrays are expanded into multiple rows of values:

rows = db.query(
    'SELECT * FROM ?? WHERE status IN (?)',
    ['demo', ['error', 'warning']],
)
# SELECT * FROM demo WHERE status IN ('error', 'warning')

affected_rows = db.non_query(
    'INSERT INTO ?? (id, name) VALUES ?',
    ['demo', [[1, 'a'], [2, 'b']]],
)
# INSERT INTO demo (id, name) VALUES (1, 'a'), (2, 'b')

Dictionary parameters are expanded into multiple assignment expressions:

affected_rows = db.non_query(
    'INSERT INTO ?? SET ?',
    ['demo', {'id': 1, 'name': 'a'}],
)
# INSERT INTO demo SET id = 1, name = 'a'

Before executing dynamic write or delete SQL, re-confirm the target table and filter conditions.