Configuration

In order to use a notebook with an ApertureDB instance, it is necessary to supply details about how to connect. Primarily, this consists of the host name, the user name, and the password. You can supply this information directly to Connector.Connector() or Configuration.Configuration(), but it is usually better to store password information outside of your source code. A more convenient approach is to call CommonLibrary.create_connector().

create_connector() looks for configuration information in a number of places. Some of these try to find an existing configuration. To create a configuration manually, see adb config create.

create_connector() will also get connection information from its environment in the form of a JSON string. This JSON string is offered as a convenience method to provide all connection information in one place. The correct contents of this JSON string will depend on how you have set up your ApertureDB instance.

Getting Your JSON String

Cloud

If you created your ApertureDB instance using our self-service ApertureDB Cloud portal, then you can obtain a JSON config by clicking on the "Connect" button for your instance.

Scroll down to "Useful Tools" and find the option to generate a connection string.

Change the username if necessary, enter your instance password, and click "CONFIRM".

The JSON connection string will be copied to your clipboard.

Local

If you are running your own copy of ApertureDB locally (perhaps using the Community Edition), and you have not changed the password from the default value, then you can probably use a JSON string like:

{
  "name": "localhost",
  "host": "localhost",
  "port": 55555,
  "username": "admin",
  "password": "admin",
}

MacOS users may need to change the port number, as 55555 is often already in use, e.g.

{
  "name": "localhost",
  "host": "localhost",
  "port": 55557,
  "username": "admin",
  "password": "admin",
}

Examples

The minimal JSON string contains three fields:

{
  "host": "[HOSTNAME]",
  "username": "admin",
  "password": "[PASSWORD]"
}

The full version has many more fields:

{
  "host": "[HOSTNAME]",
  "port": 55555,
  "username": "admin",
  "password": "[PASSWORD]",
  "name": "example",
  "use_ssl": true,
  "use_rest": false,
  "use_keepalive": true,
  "retry_interval_seconds": 1,
  "retry_max_attempts": 3
}

The name field is also required unless otherwise specified.

Storing Your JSON String

Environment Variable

One way to make your JSON string available is by putting it into the APERTUREDB_JSON environment variable:

export `APERTUREDB_JSON='{ "host": "[HOSTNAME]", "username": "admin", "password": "[PASSWORD]"}`

This approach might be useful when running scripts under Docker, as the environment variable can come from one of various possible stores of cloud secrets.

The .env File

You can make your JSON string available by storing in a .env file under the APERTUREDB_JSON key:

`APERTUREDB_JSON='{ "host": "[HOSTNAME]", "username": "admin", "password": "[PASSWORD]"}`

This approach is useful for Jupyter Notebook environments where you can rely on persistence of local file storage.

Google Colab Secret

The easiest way to configure one or more Colab notebooks to point to the same ApertureDB server is to put the JSON config into a Colab secret.

This secret will persist over runtime restarts and can be used by all of your notebooks, but it will not be exposed if you share your notebook with anyone.

1. Click on the key icon at the left of Google Colab to open the Secrets interface.
2. Click on "Add new secret"
3. Ensure that "Notebook access" is enabled
4. For the name, enter APERTUREDB_JSON
5. Paste the JSON object into the "Value" box.

You may also be asked to allow a notebook permission to access your secrets.

CLI

The adb CLI will also accept JSON strings when creating configurations. These can come from an environment variable or a .env file, but can also be entered directly in the console.

adb config create --from-json

For example, here is this being done in Google Colab:

For security reasons, the string will not be displayed in the console.

Ensure the string is pasted as a single line, e.g.:

{ "host": "[HOSTNAME]", "username": "admin", "password": "[PASSWORD]"}