VPN

Most people interact with SokweDB via a web browser. But some people may wish to run programs on their own computer that connect directly to SokweDB. A VPN is needed to secure direct connections to the SokweDB database.

Principals of Operation

Starting the SokweDB VPN creates a network endpoint on your machine that connects directly to the machine running SokweDB's database engine.

As long as the VPN is running any program on your computer can connect directly to SokweDB. When the VPN is disconnected all existing connections between your computer and SokweDB are broken. No new connections can be established until the VPN is re-started.

The VPN must be up and running throughout the lifetime of your database connection. You cannot: start the VPN, run a query, stop the VPN, re-start the VPN, and then obtain the results of your query. Your query results are lost when the VPN is shut down.

Closing your laptop lid may disconnect you from the Internet and suspend all running programs, including the VPN. At the time of this writing, you cannot be disconnected from the Internet or suspend the VPN for more than 1 minute 30 seconds without breaking the VPN connection.

Getting VPN Access

People who want VPN access are expected to follow the instructions for setting up a VPN on your computer. However if you don't like the software or approach of the supplied instructions you are free to construct your computer's side of the VPN as you choose.

As explained in the instructions, your SokweDB administrator must grant you access to the VPN. The VPN setup instructions require that you reach out to your SokweDB administrator and give them your VPN setup information. The VPN will not be available to you until you hear back from your SokweDB administrator.

Adding the VPN to Another Computer

Using the VPN on multiple computers requires copying some files from one computer to another, as the VPN setup instructions explain. (In particular, you should not create a 2nd digital identity on your 2nd computer.)

To setup and use the VPN on a 2nd computer does not require contact with the SokweDB administrator. The exception being when you have lost the digital identity created when you first setup the VPN.

Using the VPN

• Start the VPN by clicking on its icon.
• A window will open. It displays some text explaining how to connect your program to SokweDB.
• Run whatever programs you wish that make connections to SokweDB.
• To shut down the VPN either type any character in the VPN window, or close the window.

Connection Details Your Program Needs

In order to connect to SokweDB the program you're running needs some information, termed connection parameters. Sometimes the program asks for the connection parameters piecemeal, and sometimes the program will want all the information bundled together into a connection string.

These are the essential connection parameters:

host

localhost

port

5432 This is the PostgreSQL default so you may not need to give your program this parameter.

user

Your SokweDB login.

password

Your SokweDB password. It is best not to store your password, unless it is encrypted. If your program can prompt you for a password whenever it is run then this parameter can be omitted, and storage of the password is thereby avoided.

dbname

sokwedb Of course you can connect to another database, like sokwedb_test, by supplying a different value.

sslmode

required Other values will work, so long as encrypted connections can happen. Your program may or may not default to encrypting connections. If the default is to encrypt then this parameter need not be set.

Examples

There are (almost) as many different ways to supply PostgreSQL connection information as there are programs. Two common ways to supply connection parameters are with connection strings and connection URIs.

Connection String

An example Postgres connection string is:

host=localhost port=5432 user=YOU password=YOURPASS dbname=sokwedb sslmode=require

Where:

YOU

Is your SokweDB user name, which grants you access to PostgreSQL

YOURPASS

Is your SokweDB password, which goes with your SokweDB user name

Connection URI

The same connection parameters as a connection URI looks like:

postgresql://YOU:YOURPASS@localhost:5432/sokwedb?sslmode=require

Leaving the default port of 5432 unspecified, a shorter URI which works like the one above looks like:

postgresql://YOU:YOURPASS@localhost/sokwedb?sslmode=require