> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn about best practices for the custom database action script environment.

# Custom Database Action Script Environment Best Practices

Action scripts execute as a series of called JavaScript functions in an instance of a serverless Webtask container. As part of this, a specific environment is provided, together with a number of artifacts supplied by both the Webtask container and the Auth0 <Tooltip tip="Authentication Server: Server that confirms or denies a user’s identity." cta="View Glossary" href="/docs/glossary?term=authentication+server">authentication server</Tooltip> (your Auth0 tenant) itself.

## npm modules

Auth0 serverless Webtask containers can make use of a wide range of [`npm`](https://www.npmjs.com/) modules; `npm` modules not only reduce the overall size of action script code implementation, but also provide access to a wide range of pre-built functionality.

By default, a large list of publicly-available `npm` modules are supported out-of-the-box. This list has been compiled and vetted for any potential security concerns. To see which `npm` modules are supported, read [Can I require: Auth0 Extensibility](https://auth0-extensions.github.io/canirequire/).

If you require an `npm` module that is not supported out-of-the-box, then you can make a request via the [Auth0 Extensibility portal](https://auth0-extensions.github.io/canirequire/) or through your Auth0 representative. Auth0 will evaluate your request to determine suitability, if you need to escalate an unresolved request open a support ticket via the [Auth0 support portal](https://support.auth0.com/). There is currently no support in Auth0 for the use of `npm` modules from private repositories.

## Variables

Auth0 action scripts support the notion of environment variables, accessed via what is defined as the globally-available `configuration` object. The `configuration` object should be treated as read-only and should be used for storing sensitive information, such as credentials or API keys for accessing external identity stores. This mitigates having security-sensitive values hardcoded in an action script.

The `configuration` object can also be used to support whatever Software Development Life Cycle (SDLC) best practice strategies you employ, such as [setting up multiple environments](/docs/get-started/auth0-overview/create-tenants/set-up-multiple-environments), by allowing you to define variables that have tenant-specific values. This mitigates hardcoded values in an action script, which may change depending upon which tenant is executing it.

## global object

Auth0 serverless Webtask containers are provisioned from a pool that is associated with each Auth0 tenant. Each container instance makes available a global object, which can be accessed across all action scripts that execute within it (the container instance). The global object acts as a global variable that is unique to the container and that can be used to define information—or even functions—that can be used across all action scripts that run in it (the container instance).

This means that the global object can be used to cache expensive resources, as long as those resources are not user-specific. For example, an <Tooltip tip="Access Token: Authorization credential, in the form of an opaque string or JWT, used to access an API." cta="View Glossary" href="/docs/glossary?term=Access+Token">Access Token</Tooltip> for a third-party (e.g., logging) API that provides non user-specific functionality could be stored. Or it could be used to store an Access Token to your own non user-specific API defined in Auth0 and obtained via use of the Client Credentials flow.

<Warning>
  An action script may execute in any of the container instances already running or in a newly-created container instance (which may subsequently be added to the pool). There is no container affinity for action script execution in Auth0. This means that you should avoid storing any user-specific information in the global object and should always ensure that any declaration made within the global object provides for initialization too.
</Warning>

Each time a Webtask container is recycled, or for each instantiation of a new Webtask container, the global object it defines is reset. Thus, any declaration of assignment within the global object associated with a container should also include provision for initialization. To provide performance flexibility, serverless Webtask containers are provisioned in Auth0 on an ad-hoc basis and are also subject to various recycle policies. In general, we recommend that you do not consider the life of a global object to be anything more than 20 minutes.

## Custom database connection environment checklist

* Make sure that your database has the appropriate fields to store user profiles attributes, such as **id**, **nickname**, **email**, and **password**. To learn more about Auth0's user profile schema and expected fields, read [Normalized User Profiles](/docs/manage-users/user-accounts/user-profiles/normalized-user-profiles). To learn how to update user profiles, read [Update User Profiles Using Your Database](/docs/manage-users/user-accounts/user-profiles/update-user-profiles-using-your-database).
* You can use return errors resulting from your custom database connection for troubleshooting purposes.
* The `id` (or alternatively `user_id`) property in the returned user profile will be used by Auth0 to identify the user. If you are using multiple custom database connections, then the **id** value **must be unique across all the custom database connections** to avoid **user ID** collisions. Our recommendation is to prefix the value of **id** with the connection name (omitting any whitespace). To learn more about user IDs, read [Identify Users](/docs/manage-users/user-accounts/identify-users).
* Latency will be greater compared to Auth0-hosted user stores.
* The database or service must be reachable from the Auth0 servers. You will need to configure inbound connections if your store is behind a firewall.

## Testing a specific runtime version

The runtime version for custom Database scripts is defined at **Dashboard > Settings > Advanced** within the **Extensibility** section.

Follow these steps to test a single custom database script on a specific runtime version:

1. Navigate to **Authentication > Database.**
2. Select the Database connection where you have defined a custom script.
3. From within the selected database connection's page, select the **Custom Database** tab.
4. Scroll to **Database Action Scripts** section of the page.
5. Select the specific script you want to verify (eg. Login, Create etc) on the respective tab.
6. Select **Save and Try**. This loads a modal with specific test parameters and sample context details. Update as needed.
7. Select **Try** from the modal to open a dropdown selector for a specific Node version.
8. The test would trigger upon selecting the desired Node version and results would show up in a message on the same screen.

## Learn more

* [Custom Database Action Script Execution Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/execution)
* [Custom Database Connection Security Best Practices](/docs/authenticate/database-connections/custom-db/custom-database-connections-scripts/connection-security)