Skip to content

Database setup

Jump to bottom
James Cheney edited this page Sep 11, 2020 · 16 revisions

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 and running inside a VM with username ubuntu (as described here), but a similar approach should work using other databases.

  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) and Links support for that database. This can be done using OPAM:

    opam install postgresql links-postgresql

    Note that these bindings require some extra development libraries installed on your system. OPAM will guide you in case these are missing. Database drivers for using sqlite and mysql with links are provided, but not actively supported / tested at the moment.

  3. [In older versions of Links, installing a new database driver would trigger recompilation of Links itself, but this should no longer be necessary. If it is, try 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, using the credentials of the postgres user (or after assuming userid postgres by doing sudo su postgres), run the command:

    psql -c "CREATE DATABASE links;"

    Also, create a user account in the database whose name is the same as the name of the user account that will run Links programs, for example:

    psql -c "CREATE USER <username> WITH ENCRYPTED PASSWORD '<password>';"

    where is the name of the user account that will be running Links programs, and <password> is a sensible password (not the same as the password for the operating system's account!).

    For example, if doing this inside a VM with username ubuntu, you could put ubuntu for <username> and some password, say 12345678 for the password. If you choose a different username than that of the OS account, you may need to configure Postgres to allow password connections; if you do this, you should also choose a strong password (which you should probably do anyway!)

    Finally, to make sure that <username> has access to the newly created links database, do the following:

    psql -c "GRANT ALL ON DATABASE links TO <username>"

  5. Next exit the Postgres client and re-start it connecting to database links as user <username> (with the password chosen above), as follows:

    psql -d links -U <username>

    and create some tables, for example:

    CREATE TABLE test (
  i INTEGER,
  s TEXT
);

    You can also do this entirely from the command line as follows:

    psql -d links -c "CREATE TABLE test (i INTEGER, s TEXT);"

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

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

    where <username> is the username used above, account with access to the database links, and <password> is the database password associated with that user (as set above).

  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 test = table "test" with (i : Int, s : String) from db;
insert test  values (i, s) [(i=1, s="one")];
query {for (x <-- test) [x]};

    If the database is correctly configured then all four of these commands should succeed and the result of the last one should look like this:

    [(i=1,s="one")] : [(i:Int,s:String)]
Clone this wiki locally