Database setup

To run Links programs that manipulate the database you need to install one of the following database engines on your system: MySQL, PostgreSQL, or SQLite3. Once you have done that you need to compile Links with at least one of these database backends enabled.

The following instructions assume you are installing PostgreSQL, but

1. Install the postgresql package (or mysql or sqlite3 as required) using your package manager, along with any necessary development libraries, e.g. on Debian or Ubuntu this will be something like:

   apt-get install postgresql libpq-dev
   

   Once you've done that you need to configure the database by creating a new user and creating at least one database for that user. If you want to run the Links test suite you should create a database called links. Refer to PostgreSQL documentation or the respective documentation for other databases for instructions how to manage users and databases.

2. Install OCaml bindings for PostgreSQL (or other databases). This can be done using OPAM:

   opam install postgresql
   

   Note that these bindings require some extra development libraries installed on your system. OPAM will guide you in case these are missing.

3. The Links Makefile automatically detects whether the postgresql (or other database) package is installed, and if so compiles in support for the corresponding database driver(s). If you have already installed Links by building from source, you will need to re-build and re-install it. If you have installed Links using OPAM, installing the postgresql (or other) OPAM module should automatically trigger recompilation of Links. If this does not happen, you can force Links to be reinstalled using opam reinstall links, or, if all else fails, opam remove links followed by opam install links.

4. Once Links is compiled with database support, the database needs to be configured appropriately with an appropriate username and tables. We will illustrate this assuming Links is running on the same machine as a PostgreSQL database, which is running at the default port 5432. First we create a user named links on the database. To do this, start the the Postgres client as an administrator (user postgres) and run the command:

CREATE TABLE links;

5. Next exit the Postgres client and re-start it connecting to database links, and create some tables, for example:

CREATE TABLE factorials (
  i integer,
  f bigint
);

6. Now create a configuration file called config and add the following lines to it:

database_driver=postgresql
database_args=localhost:5432:<username>:links

where <username> is the username of an account with access to the database links. Alternatively this can be left blank and the current username will be assumed.

7. Finally, start Links using the command line option --config=config where the parameter value should be the filename of the configuration file.

linx --config=config

It should then be possible to access the database from query expressions in Links. You can test this by declaring the factorials table inside Links and then inserting some data into the factorials table and then querying it as follows:

var db = database "links";
var factorials = table "factorials" with (i : Int, f : Int) from db;
insert factorials  values (f, i) [(f=1, i=1)];
query {for (x <-- factorials) [x])};