The environment

The environment is a dictionary of context values held by the database object. It holds values such as the current user, the working date or the current state of a partition. Queries read it through env underscore parameters. Row policies read it, and so does the hash PERIOD macro. Each thread has its own dictionary. The environment is context only. It does not open a transaction, does not select a database and does not grant permissions.

db dot currentEnv is the live dictionary of the current thread. You change it directly. db dot current_env, with an underscore, returns a copy with a read-only outer mapping. Assigning to it raises TypeError. db dot currentUser returns the value of the key user. updateEnv sets several keys at once. None is a value, so region equal None stores None. With underscore excludeNoneValues equal True, updateEnv skips the keys whose value is None. clearCurrentEnv replaces the dictionary with an empty one. None of these calls commits, rolls back or closes a connection.

temp_env sets values for the duration of a with block. tempEnv is another spelling of the same method. On exit, a key that existed before is restored to its old value, also when the block raises. A key that the block introduced is removed, but only if its value is still the one given to temp_env. If code inside the block changed it, the new value stays. temp_env is not a transaction. In the second example an invoice is inserted inside the block. After the block, the insert is still pending in the open transaction. Only rollback removes it, and only commit makes it permanent.

Two keys have properties on the database. db dot workdate returns the key workdate, or today's date when the key is absent or false. db dot locale returns the key locale. When it is absent, it uses the environment variable GNR_LOCALE, then the locale of the Python process, then en_GB. Setting either property writes the key into currentEnv. The values are not validated. They do not change the process locale or date formatting. A colon env_workdate parameter reads the workdate with the same default, today.

The query compiles once, but env underscore values are read at every execution. The same query object returns Ada's invoices in the first block and Bob's invoices in the second. Outside both blocks the key is absent, the parameter is NULL, and the result is empty. No error is raised for an absent key. An explicit parameter takes precedence. When you pass env_customer_id to query, the value is a normal parameter, and the environment is not read for it. Some environment values change the SQL text itself, not only a parameter. These are the dates of hash PERIOD and the shape of a partition condition. Those are fixed at the first compilation. To change them, build a new query inside the new scope.

Each thread has its own environment dictionary. A new thread starts from the initial values of the database, not from the values of the thread that created it. In the example the worker thread does not see the user main, and its change does not reach the main thread. Do not pass the currentEnv dictionary to another thread or to an async task. Several async tasks in one thread share one dictionary, so asqueel does not support concurrent async tasks within one thread.

To give every thread the same starting values, pass an SqlEnvironment to AsqueelDb with the environment argument. The database copies its values when it is built. Each thread receives a copy of them on its first access to currentEnv. clearCurrentEnv empties only the dictionary of the current thread. A thread created later still starts with the initial values. The values must support deepcopy.

To recap. currentEnv is the live dictionary of the thread, and current_env is a read-only copy. temp_env restores values on exit and does not touch the transaction. env underscore values are read at every execution, and an explicit parameter takes precedence. The next lesson uses the environment to filter rows with row policies.