Deployment

System Requirements

AgensGraph requires at least 4GB of RAM and 2.5GB of disk space to run. It may run on any general Unix-compatible platforms, but the officially-certified platforms are Linux series (Centos, Ubuntu, RHEL) and Windows series (Windows Server 2008 64bits, Windows Server 2012 64bits, Windows 7 64bits).

Pre-install tasks

User account

Like other externally-accessible server daemons, it is recommended to run AgensGraph with a separate user account. If you are on Unix-compatible platforms, you can add a user account using useradd or adduser command.

   useradd agens

Kernel resource management

Shared memory and Semaphores

Shared memory and semaphores are collectively referred to as “System V IPC”, which is required to run AgensGraph. In the case where the size requested by AgensGraph exceeds the IPC limit, the server fails to start.

Name	Description	Reasonable values
SHMMAX	Maximum size of shared memory segment in bytes	At least 1kB(or more if multiple copies of the server are running)
SHMMIN	Minimum size of shared memory segment in bytes	1
SHMALL	Total amount of shared memory available(bytes or pages)	Same as SHMMAX in bytes. Ceil (SHMMAX / PAGE_SIZE) in pages
SHMSEG	Maximum number of shared memory segments per process	Only 1 segment is needed, but the default is much higher
SHMMNI	The maximum number of system-wide shared memory segments	Like SHMSEG plus room for other applications
SEMMNI	Maximum number of semaphore identifiers (e.g. set)	At least ceil ((max_connections + autovacuum_max_workers + 4) / 16)
SEMMNS	System-wide semaphore	Maximum number of ceil ((max_connections + autovacuum_max_worker + 4) / 16) * 17 and excess of other applications
SEMMSL	Maximum number of semaphores per set	At least 17
SEMMAP	The number of items in a semaphore map	Refer to text
SEMVMX	Maximum semaphore value	At least 1000 (default is usually 32767; do not change it unless needed)

AgensGraph requires several bytes of System V shared memory per server copy (usually 48 bytes for 64-bit platforms). This amount is easily allocated in the mordern operating systems. However, when running multiple copies of the server or when other applications also use System V shared memory, it may be necessary to increase SHMMAX (the maximum shared memory size in bytes) or SHMALL (the system-wide System V shared memory). Note that SHMALL is handled on a page-by-page basis rather than a byte-by-byte basis on most systems.

In the case of AgensGraph, the minimum size of the shared memory segment (SHMMIN) is about 32 bytes at most (usually 1) and is less likely to cause a problem. The maximum number of segments system-wide (SHMMNI) or the maximum number per process (SHMSEG) is highly unlikely to cause problems unless the system is set to zero.

AgensGraph uses one semaphore per connection (max_connections) and one semaphore per autovacuum worker process (autovacuum_max_workers) among the 16 sets. Each set has a 17th semaphore with a “magic number” that detects collisions with a semaphore set of other applications. The maximum number of semaphores in the system is set by SEMMNS, and at least “max_connections + autovacuum_max_workers + 1 added to 16 allowed connections + worker” (see Table 1-1 formula). The parameter SEMMNI limits the number of semaphore sets that can exist concurrently on the system. It should be at least ceil ((max_connections + autovacuum_max_workers + 4) / 16). Reducing the number of acceptable connections can be a temporary solution in case of failure, but you may receive an ambiguous message from the semget function like “No space left on device.”

In some cases, it may be necessary to increase SEMMAP so that it can be similar to SEMMNS at least. This parameter defines the size of the semaphore resource map, which contains the entries that adjacent blocks of the semaphore need. A set of released semaphores is added to the entry adjacent to the released block or is registered as a new entry. When the map is full, the released semaphore disappears (until it is rebooted). As the semaphore space is divided, the number of available semaphores becomes smaller.

SEMMSL that determines the number of semaphores to be included in a set should be at least 17 for AgensGraph.

Other settings related to “semaphore undo” such as SEMMNU and SEMUME do not affect AgensGraph.

Note: If you encounter a “Warning: Out of Shared Memory” error while performing some queries, visit SKAI Worldwide’s website and request a technical support; the team will provide you with a guide on the memory settings suitable for your site environment.

Single instance install

There are two ways to install AgensGraph. You can download the binary from the official website and download the source code and build/install it. Either way, we recommend that you work with an account for managing AgensGraph.

Installing via binary download

Download the binary or installer suitable for your operating system from S/W Download menu of official AgensGraph website.

Linux

Linux binaries are compressed with tarball. After unzipping them to the desired location, perform the post-installation task to complete the installation.

Windows

Coming soon.

Installation by Source Code Build

1. Connect to github of AgensGraph and clone the source code.

 git clone https://github.com/skaiworldwide-oss/agensgraph.git

2. Move to the clone location and run configure on the source tree. At this time, you can set the location where AgensGraph will be installed via --prefix=/path/to/install.

./configure

3. Perform a build.

make install

4. Install the extension module and binaries.

make install-world 

Post-Installation Tasks (Linux)

In the case of Unix series and Linux, if you do not register an environment variable, you will not be able to read/activate the installed libraries properly, and you will have to enter the absolute path when making a call. The above problem can be prevented by adding an environment variable to bash_profile of the user with AgensGraph installed as follows:

export AGHOME=/path/to/AgensGraph                
export AGDATA=/path/to/AgensGraph /data                 
export PATH=$AGHOME/bin:$PATH  
export LD_LIBRARY_PATH=$AGHOME/lib:$LD_LIBRARY_PATH  

Environment	Description
AGHOME	This is the directory where AgensGraph is installed.
AGDATA	Location of the data directory
PATH	Set $AGHOME/bin as the directory path to use AgensGraph.
LD_LIBRARY_PATH	This is the path where the shared library needed for using AgensGraph is located. Set $AGHOME/lib.

Operations

initDB

To run AgensGraph, you need to initialize the database storage area using initdb. Such an area is called a database cluster, which is a collection of databases managed by a single instance of a running database server. A database cluster consists of a single directory where all the data is stored. From the file system perspective, it is considered a data directory or a data area. You can set where to store this data with -D option.

initdb -D /home/agensgraph/data

Or, you can initialize the database storage area using ag_ctl.

ag_ctl initdb -D /home/agensgraph/data

initdb creates a directory if the specified directory does not exist, and denies execution if it is already initialized.

Create a role

Roles can be considered a database user or a group of database users, depending on how the database is set up. As a role can own a database object, it may assign permissions for the object to other roles to control who can access the object. As the membership of a role can be granted to other roles, you may make the member role use the permissions assigned to other roles. To create/delete a role, you should use the following SQL command.

db=# CREATE ROLE name;  
db=# DROP ROLE name;  

For your convenience, createuser and dropuser can be invoked from the shell command line (serving as the wrapper of SQL commands).

createuser name  
dropuser name  

createdb

To create/remove a database, start the AgensGraph server and create it using SQL commands CREATE DATABASE and DROP DATABASE.

db=# CREATE DATABASE name;
db=# DROP DATABASE name;

The current role that has performed CREATE DATABASE automatically becomes the owner of the new database.

For your convenience, you may create/remove databases by calling createdb and dropdb from the shell command line. You may use -O option to designate the owner of the new database that you are creating.

createdb dbname [-O rolename]  
dropdb dbname  

Startup

You should start the database server before accessing the database using ag_ctl. You need an initialized database repository to start, and have to specify the corresponding directory with -D option. If you set the database repository location via AGDATA, an environment variable, you may start the server without -D option. Using -l option, you may set logfile that will contain logs.

ag_ctl start [-D /home/agensgraph/data] [-l /home/agensgraph/data/logfile]

Shutdown

There are several ways to terminate AgensGraph. You may control the types of termination depending on which signal is sent to the master process.

Mode	Description
SIGTERM	Smart shutdown mode. The server does not allow any new connections, but waits for the old session to terminate normally before shutdown.
SIGINT	Fast shutdown mode. The server does not allow any new connections, and aborts/terminates transactions for all existing processes.
SIGQUIT	Immediate shutdown mode. The server terminates all child processes. Child processes that do not terminate within 5 seconds are forced to terminate by sending SIGKILL, which leads to recovery at the next startup. Therefore, this is recommended only in an emergency.

You can terminate ag_ctl with -m option as follows (unless -m is specified, the default is smart):

ag_ctl stop [-D DATADIR] -[m smart|fast|immediate]

```{raw} latex \pagebreak