`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,
)

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.

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 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.
`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.