 |
| 2 Getting Started |
|---|
| Back to TOC |
To get in touch with the Cego database system, we will create a sample database. Performing subsequent tasks to create the database, to start it up and connect to it using the standard client program cgclt will give a basic understanding of the system.
This assumes a successful compiliation and installation of the cego database programs. Please see the README file in the distribution for a description of the required steps.
2.1 Building up a tableset using cgmkdb
The easiest way to create a cego tableset is using the cgmkdb utility script in the tools directory. As default, the database is created in the directory /usr/local/cego. Please ensure, that the directory exists and is writable for the creating user. As an example, we create a database called cgdb with a database user lemke and a tableset called TS1 using the cgmkdb utility.
$ ./cgmkdb -u lemke -t TS1 cgdb Creating database in directory /usr/local/cego/cgdb ... Database name: cgdb * Generating database configuration xml ... OK * Creating admin user for the database ... OK * Creating role ALL ... OK + Creating role permission ... OK + Creating user:lemke ... OK * Creating a tableset ... + Defining tableset:TS1 ... OK + Finalizing tableset:TS1 ... OK * Creating database start script ... OK * Creating database stop script ... OK Done. |
The database cgdb has been created with a default tableset TS1. In a cego database, a tableset is a complete transaction space including any database objects like tables, procedures, views and so on. In addition to the basic tableset, corresponding start and stop scripts located in the subdirectory /usr/local/cego/cgdb have been generated.
The database now can be started up using the generated start script cgdb_start
$ cd /usr/local/cego/cgdb $ ./cgdb_start Starting cego with tablesets TS1 ... Cego daemon up and running ... |
To shutdown the database, the generated shutdown script cgdb_stop can be used.
$ ./cgdb_stop Stopping cego database-instance:cgdb with tableset:TS1 ... * Signaling PID:17967 ... Done. * Waiting for lockfile to clear ... This takes a few seconds. Please be patient! Lockfile cleared in 19 seconds. * Housekeeping ... Done. Database shutdown complete. |
The next section will describe, how to build up a tableset manually step by step. The unpatient user can skip this section and read about how to use the tableset.
2.2 Building up a tableset manually
To build up a cego database tableset from scratch manually is also pretty easy. The following steps illustrate the way to do so.
Step I - Create an initial database configuration file
A cego database description is based on an appropriate XML configuration file, which contains all required information about the database. As a first step, we have to create this kind of XML document. An initial configuration file can be created using the init mode of the cego program.
$ cego --mode=init --dbxml=cegodb.xml --dbname=cegodb |
As a result, the following file should be produced
<?xml version="1.0" ?> <!DOCTYPE CEGO_DB_SPEC> <DATABASE NAME="cegodb" PAGESIZE="32786" HOSTNAME="localhost" ADMINPORT="2000" LOGPORT="3000" DATAPORT="2200" PIDFILE="./pid" CSMODE="ID" MAXTSID="0" QESCMODE="ON"> <MODULE NAME="ALL" LEVEL="NOTICE"></MODULE> </DATABASE> |
If required, the file still can be modified manually, Later on, if the database is set up, the configuration file should just be edited with advanced cego knowledge.
Step II - Create a database admin user
As next, a database admin user should be created. This user is used later on to connect to the database for further admin actions. To create the database admin user, you have to call the cego program in the following manner
$ cego --mode=adduser --dbxml=cegodb.xml --user=cgadm/cgadm --role=admin |
The mode parameter adduser invokes cego in the appropriate way to setup a database user. With the parameter --dbxml, a valid configuration file is expected. We use the XML file created in the first step. Username and password are specified with the --user option. The password is stored in a encrypted form in the configuration file. The spefified user must not exist in the database configuration file.
If called successful, the configuration file should contain a admin user entry as listed below.
<?xml version="1.0"?> <!DOCTYPE CEGO_DB_CONFIG> <DATABASE NAME="cegodb" PAGESIZE="32786" HOSTNAME="localhost" ADMINPORT="2000" LOGPORT="3000" DATAPORT="2200" PIDFILE="./pid" CSMODE="ID" MAXTSID="0" QESCMODE="ON"> <USER NAME="cgadm" PASSWD="3469c5c767f9cd3dbfa6f84296c992e1" TRACE="OFF" ROLE="admin"> </USER> </DATABASE> |
In this phase, the database configuration file could still be edited manually ( for example to delete a created user entry ) If the database is started up with the corresponding file, the file in under control by the database and should NOT be edited anymore.
The configuration file is prepared now to start up the database daemon.
Step III - Start the database daemon
To receive database admin and client requests, the cego database daemon has to be started up. In a simple way, this is done with
$ cego --mode=daemon --dbxml=cegodb.xml cego daemon up and running ... |
At default, the daemon program writes a log file cego.log to the directory, the daemon is started from ( you may change this using the --logfile parameter of the cego program ). You may trace the successful start procedure of the daemon by listing the logfile ( e.g. using tail -f ) If started successful, the database is ready to receive any connection requests.
Please note : For our first sample, the directory the daemon is started from should be readable and writable for the daemon. Logfile and database files are written to this location.
Step IV - Connecting to the daemon
Before any database client requests can be served, a valid tableset must be set up. To do this, we connect to the database using the cgadm admin program.
$ cgadm --server=localhost --port=2000 --user=cgadm/cgadm CGADM > |
With the option --server and --port options, the host connection to the database server is specified. The admin host port must match with the specified value in the database configuration file. The specified user name must be a valid user account with administrator rights.
Step V - Define a tableset
Using the cgadm program, you can define a new tableset now. In a simple way, just type the following command.
CGADM > define tableset TS1; Tableset TS1 defined ok ( 0.001 s ) |
The new defined tableset should be printed, if all registered tablesets of the database are listed.
CGADM > list tableset; +-----------+----------+-------------+ | TSL | TSL | TSL | | NAME | RUNSTATE | SYNCSTATE | +-----------+----------+-------------+ | TS1 | DEFINED | SYNCHED | +-----------+----------+-------------+ Tableset list ok ( 0.000 s ) |
Step VI - Create the tableset
The new defined tableset can be created now. For this just type
CGADM > create tableset TS1; Tableset TS1 created ok ( 0.092 s ) |
The run state of the tableset should have changed to state OFFLINE
CGADM > list tableset; +-----------+----------+-------------+ | TSL | TSL | TSL | | NAME | RUNSTATE | SYNCSTATE | +-----------+----------+-------------+ | TS1 | OFFLINE | SYNCHED | +-----------+----------+-------------+ Tableset list ok ( 0.000 s ) |
You may retrieve a listing of all configured database files with the following admin command.
CGADM > list datafile for TS1; +-------------------+--------------+--------------+--------------+ | DATAFILEINFO | DATAFILEINFO | DATAFILEINFO | DATAFILEINFO | | FILENAME | FILETYPE | SIZE | USED | +-------------------+--------------+--------------+--------------+ | ./db/TS1.sys | SYSFILE | 100 | 0 | | ./db/TS1.temp | TEMPFILE | 3000 | 0 | | ./db/TS1_data.dat | APP | 10000 | 0 | +-------------------+--------------+--------------+--------------+ Tableset information ok ( 0.000 s ) |
Please note : In tableset offline state, the used sizes of the datafiles are not indicated. This is done, if the tableset is online.
Step VII - Start the tableset
The created tableset now is set to online state by using the start command
CGADM > start tableset TS1; Tablset TS1 started ok ( 0.003 s ) |
The resulting run state of the tableset should be changed to
CGADM > list tableset; +-----------+----------+-------------+ | TSL | TSL | TSL | | NAME | RUNSTATE | SYNCSTATE | +-----------+----------+-------------+ | TS1 | ONLINE | SYNCHED | +-----------+----------+-------------+ Tableset list ok ( 0.000 s ) |
Now the used size of the datafiles should be indicated correctly.
CGADM > list datafile for TS1; +-------------------+--------------+--------------+--------------+ | DATAFILEINFO | DATAFILEINFO | DATAFILEINFO | DATAFILEINFO | | FILENAME | FILETYPE | SIZE | USED | +-------------------+--------------+--------------+--------------+ | ./db/TS1.sys | SYSFILE | 100 | 16 | | ./db/TS1.temp | TEMPFILE | 3000 | 15 | | ./db/TS1_data.dat | APP | 10000 | 0 | +-------------------+--------------+--------------+--------------+ Tableset information ok ( 0.000 s ) |
Step VIII - Create role and user
As a last administration step, we add an appropriate database role and user.
CGADM > create role ALL; Role ALL created ok ( 0.000 s ) |
CGADM > set permission TS1_P with tableset=TS1, filter='ALL', right=ALL for ALL; Permission TS1_P set ok ( 0.000 s ) |
CGADM > add user lemke identified by 'lemke'; User lemke added ok ( 0.001 s ) |
To allow user lemke to perform any database operation, the previous created role ALL is assigned to the user
CGADM > assign role ALL to lemke; Role set for user lemke ok ( 0.013 s ) |
Now the database is ready to use by user lemke. In the next section, we will see how the database can be used by this user.
2.3 Using the first tableset
The cgclt program can be used to perform database user requests. We invoke the client program with the following command
$ cgclt --server=localhost --port=2200 --tableset=TS1 --user=lemke/lemke CGCLT > |
Now we can create our first table object using the following sql command
CGCLT > create table mytab ( primary a int not null, b string(30) ); Table mytab created ok ( 0.002 s ) |
The created table can be checked using the tableinfo command. Since we have specified column a as a primary key, a primary index has also been created for the table.
CGCLT > tableinfo mytab; +-------------------------------+----------------+----------------+ | TABLEINFO | TABLEINFO | TABLEINFO | | NAME | TYPE | PAGES | +-------------------------------+----------------+----------------+ | mytab | table | 1 | | mytab_pidx | primary index | 1 | +-------------------------------+----------------+----------------+ ok ( 0.002 s ) |
To put data into the table, you can use the SQL insert command
CGCLT > insert into mytab values ( 42, 'this is mytext'); Query executed ok ( 0.001 s ) |
Finally, the inserted data can be retrieved using a SQL select command
CGCLT > select * from mytab; +-----------+-------------------------------+ | | | | a | b | +-----------+-------------------------------+ | 42 | this is mytext | +-----------+-------------------------------+ ok ( 0.023 s ) |
If you have reached this step, your cego database system basically is running for you. Please see the subsequent chapters for a more detailed view about the features of the system.