# Connecting to a Database
Before using ChemRecon, the library needs to be connected to a database.
For this, there are several options.
 - A public ChemRecon database is available, hosted by the University of Southern Denmark. By default, ChemRecon will connect to this databae.
 - A local Docker container can be hosted based on a ChemRecon database image [(see docs)](./selfhost_db.md).
   - By default, ChemRecon assumes that container port `5432` is bound to port `54320` on the host machine.
 - For other options, ChemRecon can connect to an arbitrary PostgreSQL endpoint.

Connecting will create a global {class}`.QueryHandler` object, used by default for all queries.
The {class}`.QueryHandler` object can be accessed using the {func}`.get_query_handler` function.
```{eval-rst}
.. autofunction:: chemrecon.connection.get_query_handler
```


## Connecting to the Public Database
If nothing else is specified, ChemRecon will connect to the public database.

```{eval-rst}  
.. autoclass:: chemrecon.connect_public

```

## Hosting a Local database
Hosting the database locally is as easy as deploying a Docker container 
(see the [Docker documentation](https://docs.docker.com/)).
See the [documentation page](./selfhost_db.md) for details.

Hosting the database locally has several advantages:
 - Queries will be faster, as there is a lower response time.
 - Results of procedural queries can be cached in the local database, making subsequent queries of these relations much faster.

After deploying the Docker image, the library can connect (with or without write access) using the following functions.
Note that these functions assume the database is hosted on port `54320` on the host machine, as specified in the Docker image.
If running on a different port, custom connection parameters must be specified (see: {class}`.Params`).

```{eval-rst}
.. autoclass:: chemrecon.connect_local_docker

```

```{eval-rst}
.. autoclass:: chemrecon.connect_local_docker_dev

```

## Connecting to an arbitrary PostgreSQL endpoint
Finally, ChemRecon can connect to any PostgreSQL endpoint.
```{eval-rst}
.. autofunction:: chemrecon.connection.connect
```
This takes a {class}`.Params` object as input, which contains the connection parameters.
This can be used to specify custom connection parameters, such as a custom port.
```{eval-rst}
.. autoclass:: chemrecon.database.params.Params
```

## Extending the database
Another advantage of hosting a local database is that you can extend the database to include custom data sources.
See the [documentation page](./building_db.md) for instructions.