Database profiles
A database profile describes a database connection that agents query through the db command. The profile holds the connection string and the pool settings for that connection.
Settings
| Field | Type | Default | Description |
|---|---|---|---|
secretsUsed | list of string | The secret names this profile's expressions read (sys.secret['NAME']). Worked out by the cloud when the profile is saved and sent with the profile to agent servers; anything sent in this field is ignored. | |
namerequired | string | The name this profile is referred to by, in agents and in other configuration. | |
doc | string | Free-text notes about this profile, for whoever maintains the configuration. | |
connectionString | dynamic string | The database connection string. It must specify an async driver installed in your Python environment: sqlite+aiosqlite, mysql+aiomysql, postgresql+asyncpg or oracle+oracledb. When it comes out different from the one a pool was opened with, for example after a password is rotated, that pool is closed and a new one opened. | |
poolKey | dynamic string | Leave empty to share one connection pool across every run that uses this profile. If the connection string differs per user, for example because each user connects with their own credentials, set this to an expression that tells them apart, such as { sys.userEmail }, so each gets their own pool. | |
connectionPool | DbConnectionPool | Pool settings for connections to this database. |
Connection pool
| Field | Type | Default | Description |
|---|---|---|---|
isolationLevel | "READ COMMITTED" | "AUTOCOMMIT" | The transaction isolation level, such as 'READ COMMITTED' or 'AUTOCOMMIT'. Leave unset for the driver's default. | |
poolSize | integer | 3 | The number of connections kept open in the pool. |
poolTimeout | integer | 5 | How long to wait for a free connection before failing. |
poolRecycle | integer | -1 | Close and reopen a connection after this many seconds. -1 disables recycling. |
poolPrePing | boolean | false | Test a connection before using it, so stale ones are not handed out. |
maxOverflow | integer | 10 | How many extra connections may be opened above the pool size during a burst. |
connectArgs | object of string → JSON value | Arguments passed straight through to the database driver. Certificate files belong here. | |
idleTimeout | integer | 300 | Close a pool and its connections after it has not been used for this many seconds. 0 keeps it open until the profile changes. |
An agent server keeps one pool per profile. When the connection string changes, for example after a vault secret is rotated, the old pool is closed and a new one opened. With poolKey set, there is one pool per distinct value of the expression, for example one per user. A pool that has not been used for idleTimeout seconds is closed.
The connection string names an async SQLAlchemy driver, which must be installed in the agent server's environment: postgresql+asyncpg://..., mysql+aiomysql://..., oracle+oracledb://..., mssql+aioodbc://..., sqlite+aiosqlite:///path. The connection string is a dynamic string, so the password can come from sys.secret.