=pod

=head1 NAME

UR::Env - Environment variables that control UR behavior

=head1 DESCRIPTION

UR uses several environment variables to change its behavior or provide
additional debugging information.

=over 4

=item UR_STACK_DUMP_ON_DIE <bool>

When true, has the effect of turning any die() into a Carp::confess, meaning
a stack dump will be printed after the die message.

=item UR_STACK_DUMP_ON_WARN <bool>

When true, has the effect of turning any warn() into a Carp::cluck, meaning
a stack dump will be printed after the warn message.

=item UR_CONTEXT_ROOT <string>

The name of the Root context to instantiate when the program initializes.
The default is UR::Context::DefaultRoot.  Other Root Contexts can be used,
for example, to connect to alternate databases when running in test mode.

=item UR_CONTEXT_BASE <string>

This value only changes in a sub-process which goes to its parent
process for object I/O instead of the root (which is the default
value for the base context in an application).

=item UR_CONTEXT_CACHE_SIZE_HIGHWATER <integer>

Set the object count highwater mark for the object cache pruner.  See also
L<UR::Context/object_cache_size_highwater>

=item UR_CONTEXT_CACHE_SIZE_LOWWATER <integer>

Set the object count lowwater mark for the object cache pruner.  See also
L<UR::Context/object_cache_size_lowwater>

=item UR_DEBUG_OBJECT_RELEASE <bool>

When true, messages will be printed to STDERR whenever objects are removed
from the object cache, such as when the object pruner marks them for removal,
when they are garbage collected, unloaded, or deleted.

=item UR_DEBUG_OBJECT_RELEASE <bool>

When true, messages will be printed to STDERR whenever the object pruner finishes
its work, and show how many objects of each class were marked for removal.

=item UR_CONTEXT_MONITOR_QUERY <integer>

When true (non-zero), messages will be printed as the Context satisfies queries,
such as when get() is called on a class, or while processing an iterator created
through SomeClass->create_iterator and iterator->next().  If the value is 1,
then only queries about Non-UR classes are printed.  If 2, then all queries' 
information is printed.

=item UR_DBI_MONITOR_SQL <bool>

If this is true, most interactions with data sources such as connecting,
disconnecting and querying will print messages to STDERR.  Same as
C<UR::DBI-E<gt>monitor_sql()>.  Note that this affects non-DBI
data sources as well, such as file-based data sources, which will
render file I/O information instead of SQL.

=item UR_DBI_SUMMARIZE_SQL <bool>

If true, a report will be printed to STDERR as the program finishes about what
SQL queries have been done during the program's execution, and how many times
they were executed.  This is helpful during optimization.

=item UR_DBI_MONITOR_EVERY_FETCH <bool>

Used in conjunction with UR_DBI_MONITOR_SQL, tells the data sources to also
print messages to STDERR for each row fetched from the underlying data
source. Same as C<UR::DBI-E<gt>monitor_every_fetch()>.

=item UR_DBI_DUMP_STACK_ON_CONNECT <bool>

Print a message to STDERR only when connecting to an underlying data source.
Same as C<UR::DBI-E<gt>dump_stack_on_connect()>

=item UR_DBI_EXPLAIN_SQL_MATCH <string>

If the query to a data source matches the given string (interpreted as a
regex), then it will attempt to do an "explain plan" and print the results
before executing the query. Same as C<UR::DBI-E<gt>explain_sql_match()>

=item UR_DBI_EXPLAIN_SQL_SLOW <float>

If the time between a prepare and the first fetch of a query is longer than
the given number of seconds, then it will do an "explain plan" and print the
results.  Same as C<UR::DBI-E<gt>explain_sql_slow()>

=item UR_DBI_EXPLAIN_SQL_CALLSTACK <bool>

Used in conjunction with UR_DBI_EXPLAIN_SQL_MATCH and UR_DBI_EXPLAIN_SQL_SLOW,
prints a stack trace with Carp::longmess.  Same as C<UR::DBI-E<gt>explain_sql_callstack()>

=item UR_DBI_MONITOR_DML <bool>

Like UR_DBI_MONITOR_SQL, but only prints information during data-altering
statements, like INSERT, UPDATE or DELETE.  Same as C<UR::DBI-E<gt>monitor_dml()>

=item UR_DBI_NO_COMMIT <bool>

If true, data source commits will be ignored.  Note that saving still occurs.
If you are working with a RDBMS database, this means During
UR::Context->commit(), the insert, update and delete SQL statements will be
issued, but the changes will not be committed.  Useful for testing.  Same
as C<UR::DBI-E<gt>no_commit()>

=item UR_USE_DUMMY_AUTOGENERATED_IDS <bool>

If true, objects created without ID params will use a special algorithm to
generate IDs.  Objects with these special IDs will never be saved to a
data source.  Useful during testing.  Same as C<UR::DataSource-E<gt>use_dummy_autogenerated_ids>

=item UR_USED_LIBS

If true, prints a message to STDERR with the contents of @INC just before
the program exits.

=item UR_USED_MODS

If true, prints a message to STDERR with the keys of %INC just before the 
program exits.  This will be a list of what modules had been loaded during
the life of the program.  If UR_USED_MODS is greater than 1, then it will
show the key/value pairs of %INC, which will show the path each module was
loaded from.

=back

=cut