Configuring the EDB Postgres AI agent to register your Oracle database Innovation Release

This documentation covers the current Innovation Release of EDB Postgres AI. See also:

Hybrid Manager dual release strategy
Documentation for the current Long-term support release

Configure the Hybrid Manager (HM) agent (deployed as beacon-agent) to establish a secure connection with HM and retrieve necessary schema and migration data from your Oracle source database.

Prerequisites

Create a machine user and access key with the estate ingester role assigned to it.

Store the access key in an environment variable named $BEACON_AGENT_ACCESS_KEY so the EDB Postgres AI agent can access it later.

Obtain HM connection parameters

The EDB Postgres AI agent requires specific configuration values that are set during the HM installation. Only an administrator or installer can access these. Contact the administrator or installer of your HM instance to request the following values:

Beacon server hostname: When configuring the HM installation, administrators/installers must specify an internal endpoint for the beacon_server service. Ask the administrator or installer of your HM instance to provide the hostname (URL) they set for the beacon_server service in the Helm chart configuration file used for installation. For this, they'll look up the value they set for parameters.upm-beacon.server_host (or BEACON_SERVICE_DOMAIN_NAME) in the values.yaml file. You will need this value later to configure the EDB Postgres AI agent.
Root certificate path (if required):The EDB Postgres AI agent requires a trusted connection to the beacon_server service in your HM instance. If the server running the EDB Postgres AI agent doesn't inherently trust HM's TLS certificate (managed by your organization's security infrastructure), ask the administrator or installer of your HM instance to provide the file with the certificate. Store this certificate on the machine running the EDB Postgres AI agent. You'll need to provide the directory path to this certificate later to configure the EDB Postgres AI agent.

See Administrative tasks for more information about the beacon_server and root certificate.

Define source database connection parameters

The DSN is the connection string the EDB Postgres AI agent uses to connect to your Oracle source database. Set the databases.dsn parameter using an environment variable $DSN or direct URL format.

A DSN string for connections to Oracle databases must use this format:

DSN="oracle://<username>:<password>@<host>:<port>/<oracle_db_name>"

Where:

<username> and <password> correspond to the user you granted permissions when preparing the database.
<host> is the hostname of the instance where your Oracle database is running.
<port> ist the port number of the database you want to fetch data from.
<oracle_db_name> is the catalog or name of the database you want to fetch data from.

For example, to connect as user oracle authenticated with password password to a database ORCLPDB1 on port 1521 (assuming the agent is running on the same instance as the Oracle database):

DSN="oracle://oracle:password@localhost:1521/ORCLPDB1"

Special characters in passwords

If your Postgres or Oracle user's password contains special, non-ASCII characters, use the URL-encoded version of the password in the DSN string (or password environment variable). For example, if your password is pa$$word, encode the $$ characters as %24%24:

DSN="oracle://oracle:pa%24%24word@localhost:1521/ORCLPDB1"

If you plan to connect to more than one database with the EDB Postgres AI agent, you can specify multiple such connection strings. For example, if you're using environment variables for the database.dsn settings, specify $DSN1, $DSN2. You can use any name you want for these variables because they'll be referenced by name in the configuration file.

Prepare a configuration file

Prepare a configuration file for your agent.

Create an EDB Postgres AI agent configuration directory in your home directory:
```
mkdir ${HOME}/.beacon
```
Note
If this location isn't convenient, you can also use either:
- /etc/beacon
- The directory from which you execute any beacon-agent command
The EDB Postgres AI agent looks for its configuration file starting with /etc/beacon, then ${HOME}/.beacon. As a final fallback, it searches the directory from which it's executed.
Inside this directory, create a file beacon_agent.yaml:
```
touch .beacon/beacon_agent.yaml
```

Copy and paste the following template into the new file. This template is designed to enable the HM console to generate a migration assessment and ingest all schemas for assessment and import.

In this template, $BEACON_AGENT_ACCESS_KEY and $DSN are the environment variables you configured previously. Replace all < > placeholders in the template. See Parameter reference for details.

---
agent:
  access_key: $BEACON_AGENT_ACCESS_KEY
  beacon_server: <beacon_server>:9443
  project_id: <project_id>
  providers:
    - "onprem"
  root_ca_path: ""
  schema_providers:
    - "onprem-schema"
provider:
  onprem:
    clusters:
      - resource_id: "<cluster_resource_id>"
        name: "<cluster_name>"
        nodes:
          - resource_id: "<node_resource_id>"
            dsn: $DSN
            schema:
             enabled: true
            poll_interval: 15s 
            tags:
              - "<tag_names>"

Save the file.

After configuring the EDB Postgres AI agent, you can run it or configure it to run as a service.

Recommendations for setting environment variables

Although you can set all parameters directly in the config file, we recommend handling sensitive data, such as $BEACON_AGENT_ACCESS_KEY or $DSN, as environment variables managed through a secrets manager. This strategy prevents sensitive credentials from being stored in plaintext configuration files. If you use environment variables, make sure they're available to the EDB Postgres AI agent while it's running.

Consult your organization's IT department on the safest approach for production environments.

For short-lived migrations or testing and demo purposes, you can use the export command in an active terminal session.

For more granular control of schema ingestion (for example, to exclude or include schemas), see Defining a subset of schemas for ingestion.
To support the ingestion of a large number of databases, see Performing multiple concurrent schema ingestions
If your administrator requires some guidance on how to obtain the values for the root certificate and beacon_server, see Administrative tasks.

← Prev

Installing the EDB Postgres AI agent to register your Oracle database

↑ Up

Migrate your Oracle database to an HM-managed database

Running the EDB Postgres AI agent