`Configuration`

Use Configuration to create the connection settings that an OracleVecDB client uses.

Configuration is the public configuration entry point. It returns the correct configuration instance for the selected connection mode.

Constructor

Use the constructor to select the endpoint type and authentication method.

Configuration(
    rest_url=None,
    access_token=None,
    username=None,
    password=None,
    connection=None,
    debug=None,
    ssl_ca_cert=None,
    ca_cert_data=None,
    retries=None,
    timeout=None,
    max_retry_delay=60.0,
)

Parameter	Type	Value Range	Required	Default	Description	Notes
`rest_url`	`str`	HTTPS ORDS `/vecdb/` endpoint	Conditional	None	ORDS REST endpoint used for API calls.	Required when you do not pass `connection`.
`access_token`	`str`	Bearer token	Conditional	None	Bearer token used for ORDS REST authentication.	Use either `access_token` or `username` and `password` when the endpoint requires authentication.
`username`	`str`	Valid database user name	Conditional	None	User name used for HTTP basic authentication.	Must be paired with `password`.
`password`	`str`	Valid password	Conditional	None	Password used for HTTP basic authentication.	Must be paired with `username`.
`connection`	`oracledb.Connection`	Open database connection	Conditional	None	SQL*Net connection object used instead of ORDS REST.	Mutually exclusive with `rest_url`.
`debug`	`bool`	`True`, `False`	No	None	Enables or disables debug logging.	Defaults to `False`.
`ssl_ca_cert`	`str`	File path	No	None	Path to a CA certificate bundle used to verify HTTPS requests.	Use only when the endpoint requires a custom CA certificate.
`ca_cert_data`	`str` or `bytes`	PEM or DER certificate data	No	None	CA certificate data used to verify HTTPS requests.	Use as an alternative to `ssl_ca_cert`.
`retries`	`int`	0 or greater	No	None	Retry count used by the REST client.	Omit to use the default generated-client retry policy.
`timeout`	`float` or `tuple[float, float]`	Positive seconds	No	None	HTTP request timeout.	A number sets the total timeout. A `(connect, read)` tuple sets separate connection and read timeouts.
`max_retry_delay`	`float`	Finite, nonnegative seconds	No	`60.0`	Maximum delay before a retry of a transient HTTP 429 response.	Caps jittered retry delays and server-provided `Retry-After` values.

Raises InsecureConnectionError is raised for an http:// URL. InvalidHostFormatError is raised when the REST URL does not match the required ORDS structure.

Pass rest_url for ORDS REST access, or pass connection for SQL*Net access. Do not pass both in the same configuration.

Environment variables

For ORDS REST configurations, you can set the following environment variables instead of passing the corresponding Configuration parameters. Values passed to Configuration take precedence over environment-variable values.

Environment Variable	Configuration Parameter	Description
`VECDB_REST_URL`	`rest_url`	Sets the ORDS REST endpoint when you do not pass `rest_url` to `Configuration`.
`VECDB_USERNAME`	`username`	Sets the user name for HTTP basic authentication when you do not pass `username` to `Configuration`. Set this variable with `VECDB_PASSWORD`.
`VECDB_PASSWORD`	`password`	Sets the password for HTTP basic authentication when you do not pass `password` to `Configuration`. Set this variable with `VECDB_USERNAME`.

Examples

Use one authentication method for an ORDS REST configuration.

Configure with a bearer token

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(
    Configuration(
        rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
        access_token="<bearer-token>",
    )
)

Configure with a user name and password

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(
    Configuration(
        rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
        username="<user>",
        password="<password>",
    )
)

Configure with a custom CA certificate

from oracle_vecdb import OracleVecDB, Configuration

client = OracleVecDB(
    Configuration(
        rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
        access_token="<bearer-token>",
        ssl_ca_cert="/path/to/ca-bundle.pem",
    )
)

Configure HTTP timeouts and retry delays

Set timeout to a positive number for a total HTTP request timeout. Set it to a (connect, read) tuple to limit connection and read time separately. The timeout applies to SDK HTTP requests, not asynchronous job completion or polling loops.

Set max_retry_delay to limit the wait before retrying a transient HTTP 429 response. When the service returns Retry-After, the SDK honors the value up to this limit. Without Retry-After, the SDK uses a bounded jittered delay.

from oracle_vecdb import OracleVecDB, Configuration

config = Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>",
    timeout=(10.0, 60.0),
    max_retry_delay=30.0,
)
client = OracleVecDB(config)

# Increase the read timeout if ORDS takes longer than 60 seconds to respond.
config.timeout = (10.0, 120.0)

If a slow ORDS operation exceeds the configured HTTP timeout, increase the applicable timeout and retry. This setting does not extend asynchronous job completion or polling loops.

Configure an HTTP proxy

Create the REST configuration first, then set the proxy attributes before you create the client.

from oracle_vecdb import OracleVecDB, Configuration

config = Configuration(
    rest_url="https://<host>/ords/<schema>/_/db-api/stable/vecdb/",
    access_token="<bearer-token>",
)
config.proxy = "http://proxy.example.com:8080"
config.proxy_headers = {
    "Proxy-Authorization": "Basic <base64-credentials>"
}

client = OracleVecDB(config)

Use proxy_headers only when the proxy requires custom headers, such as proxy authentication. Proxy settings apply to ORDS REST connections, not SQL*Net connections.

Attributes

These attributes are available on the resolved configuration instance returned by Configuration(...).

Attribute	Type	Description
`rest_url`	`str`	REST endpoint used by ORDS-backed clients. Returns an empty string when the configuration uses SQL*Net.
`connection`	`oracledb.Connection` or `None`	SQLNet connection object used by SQLNet-backed clients.
`username`	`str` or `None`	User name used for HTTP basic authentication.
`password`	`str` or `None`	Password used for HTTP basic authentication.
`access_token`	`str` or `None`	Bearer token used for ORDS REST authentication.
`debug`	`bool`	Shows whether debug logging is enabled.
`logger_file`	`str` or `None`	Path to the debug log file when file logging is enabled.
`verify_ssl`	`bool`	Controls SSL/TLS certificate verification for HTTPS requests. Defaults to `True`.
`ssl_ca_cert`	`str` or `None`	Path to the CA certificate bundle used to verify HTTPS requests.
`ca_cert_data`	`str`, `bytes`, or `None`	CA certificate data used to verify HTTPS requests.
`retries`	`int` or `None`	Retry count used by the REST client.
`timeout`	`float`, `tuple[float, float]`, or `None`	HTTP request timeout in seconds. A tuple sets separate connection and read timeouts.
`ords_settings.max_retry_delay`	`float`	Maximum delay in seconds before a retry of a transient HTTP 429 response. Defaults to `60.0` and caps `Retry-After` values.
`proxy`	`str` or `None`	Proxy URL used by ORDS REST requests. Set after creating the configuration object.
`proxy_headers`	`dict` or `None`	Optional headers sent to the proxy, such as proxy authentication headers.
`has_rest_url`	`bool`	`True` when the configuration uses an ORDS REST endpoint.
`has_sqlnet_connection`	`bool`	`True` when the configuration uses a SQL*Net connection.
`host`	`str`	Compatibility alias for the generated host setting. Use `rest_url` in new code.

Methods

These methods are available on the resolved configuration instance returned by Configuration(...).

Method	Return Type	Description
`auth_settings()`	`dict`	Returns authentication settings built from `access_token` or `username` and `password`.
`get_basic_auth_token()`	`str` or `None`	Returns the HTTP basic authentication header value derived from `username` and `password`.
`to_debug_report()`	`str`	Returns environment and SDK version details for diagnostics.
`set_default(default)`	`None`	Sets the process default configuration object.
`get_default()`	`Configuration`	Returns the default configuration object.
`get_default_copy()`	`Configuration`	Compatibility alias for `get_default()`.
`get_api_key_with_prefix(identifier, alias=None)`	`str` or `None`	Returns an API key value with its configured prefix. Most users should use `access_token` instead.
`get_host_settings()`	`list[dict]`	Returns generated host settings used by the REST client.
`get_host_from_settings(index, variables=None, servers=None)`	`str`	Resolves the REST endpoint from generated host settings.