Chapter 1: Create a Database

This chapter explains how to create a database.

  

Database Creation, Basic Information

 

Database Administrator

Database Owner

Each database requires a directory for its configuraton and system files. The owner of this directory is the "database administrator" or "dba".

Only the dba for a database can perform certain administrative tasks on a database, such as adding or removing users.

After a database has been created, you can change its database administrator by changing the ownership of its database directory.

  

Where Databases Can Be Created

Personal and group databases can be created on a local disk or on a server machine. The process of creating a database is the same for servers and local disks.

Before you can create any databases, you need to designate a database root directory. For each new database one subdirectory containing database specific information will branch from the database root directory.

The database root directory can be located anywhere. It does not have to branch from the VERSANT software root directory. If you specify relative paths to the database volumes at the time each database associated with your installation is created (the default), you can easily move the location of the database root directory later.

The directory for each database must have the same name as the database.

Three volumes provide storage for each database: a system volume, a physical log volume, and a logical log volume. These volumes can be located anywhere. Additional storage volumes for the database can be created at any time.

To maximize performance, the system and data volumes, the physical log volume, and the logical log volume should be placed on separate disk drives. Placing the volumes on different drives minimizes disk seek time and thus maximizes throughput. If performance is not a critical issue, all volumes can be put on the same disk drive, which is simpler to do than separating them.

  

Database System Identifier File, osc-dbid

osc-dbid

The osc-dbid file is explained in detail in the chapter "Directories and Files."

In brief, the osc-dbid file keeps track of all database identifiers in a network of distributed databases: the database name, the database id, the creator, and the creation date. It is automatically updated for each new database.

If you want to add a new database to a distributed database system, the machine creating the database must be part of the existing network of VERSANT databases when the new database is created.

If the osc-dbid file for a distributed database system is destroyed, you cannot create new databases or list existing ones until you recover the osc-dbid file from a backup copy or create a new osc-dbid file. To create a new osc-dbid file, use the dbid utility.

To see the information in osc-dbid, run the VERSANT dblist utility.

For example, for the database my_database, the command

dblist -d my_database

...might return:

ID            = 81
DB name       = my_database
creator       = silas
date created  = 14:48:15 92/4/26
DB type       = personal
version       = 2.1.3

The location of the osc-dbid file is specified during the first installation of VERSANT in a particular database network.

  

Database Components

The principal components of a database are:

System Volume

The System Volume contains database system catalogs and provides data storage space.

 Storage Volumes

Optional Storage Volumes are added using the addvol utility to supply more storage space if the System Volume is not big enough.

 Physical Log Volume

The Physical Log Volume contains physical data information for logging and recovery.

 Logical Log Volume

The Logical Log Volume contains transaction undo and redo information for logging, recovery, and rollback.

 For non-UNIX operating systems, database volumes must be files.

UNIX notes

•     A database on UNIX can use either files or raw devices for the database volumes. If you are using files, they may be local or remote.

•     If the database volumes are remote UNIX files, they may be accessed through NFS. However, we strongly discourage you from accessing database files through NFS, because the NFS protocol does not guarantee that file writes are flushed to disk on invocation of a flush system call. This means that use of NFS could result in database corruption!

It is much better to create a database on the host where the file system is physically located and then access it with VERSANT db@host protocol rather than with NFS protocol. This allows a VERSANT server process to directly access the database files and will improve performance.

 •     If you want to use a UNIX raw device for a database volume, make sure that the partition you use does not include cylinder 0 or cylinder 1. When a UNIX partition is used for a raw device, all cylinders allocated to that partition will be used.

•     If the UNIX partition is located on 'a' or 'c' ('c' implies the entire disk), the disk label can be overwritten.

The workaround is to make partition 'a' two cylinders long and then start partition 'b' at cylinder 2. You can then safely use partition 'b' for raw devices.

 •     If you use a UNIX raw device for the physical and/or logical log volumes, you may run out of space, because raw devices cannot be dynamically expanded by VERSANT. By contrast, if you use files for the log volumes, VERSANT will increase the log volume sizes when necessary. Of course, the log files cannot expand if their disk partition is full.

•     In order to create database volumes on UNIX raw devices, you must make the person who will create the database the owner of the device, and give the database owner read-write permissions.

  

What You Must Specify During Creation of Database Directories

When creating database directories with makedb, you must specify the following parameters. All but the first parameter use a default setting, if omitted. These parameters cannot be changed after the database has been created.

Database name

The database name must be no longer than 31 characters. When referring to a remote database, you must append a site name using the database@node syntax. The site name node must be no longer than 223 characters.

 Databse type

The database type can be either personal or group. The default is personal.

 Database owner

The default owner is the username of the person creating the database.

  

What You May Optionally Specify During Database Creation

When creating a database with createdb, you can set the following optional parameters in the database server process profile file profile.be. If you do not explicitly set any values, the defaults are used. These parameters cannot be changed after the database has been created.

Database size.

The defaults are:

System Volume         10 megabytes
Physical Log Volume    2 megabytes
Logical Log Volume     2 megabytes

If the log volumes are files, they will expand as necessary during database use. The system volume does not grow. To increase storage for data after the database has been created, you can add more volumes by using the addvol utility.

The minimum size for each log volume is 256 kilobytes.

 Database volume file names.

In the database server process profile file profile.be, you can specify paths and file names for the database volumes. The paths and names determine where the volumes are located and whether they are files or UNIX raw devices. The default is to use file volumes.

 An absolute or relative path to the VERSANT database volumes.

Each database must have a directory branching from the database root directory. In this directory environment files for the database are located. The name of a database directory must be the same as the database name.

The directory for a database can also hold the database volumes if they are files. If you use raw devices, of course, the volumes will not be located in the database.

If the path to the database volumes is specified in relative terms when the database is created, then the database volumes can be moved later. If the path is specified in absolute terms, the volumes can never be moved. The default is to specify a relative path to the database volumes.

 Note — You can change the following parameters after a database has been created, but they are so important that you might think about their values now. Each of these parameters may be set in the database server process profile file profile.be:

Locking

Whether locking is to be on or off. The default for group databases is locking on, and the default for personal databases is locking off.

 Logging

Whether logging is to be on or off. The default for all databases is logging on..

  

Database Creation Procedures

 

Steps to Create a Database

These are the steps required to create a database. They are explained in detail in the following sections.

1.  Set up database directories and default profiles

Before creating a database, you have to create a database directory, assign access privileges, and create database profiles. You can use the VERSANT makedb utility to create the necessary default setup.

 2.  Optionally edit database profile

You must edit the database server process profile if you want to create a database with a system volume size other than the default size or if you want to use a UNIX raw devices for database volumes. The name of the database profile is profile.be, and it will be located in the database directory after you run the makedb utility.

 3.  Create the database

Create the database by running the VERSANT createdb utility. The createdb utility will create the database including storage and log volumes and update the network database identifier file osc-dbid to register the new database as part of the database system.

 4.  Move a database

With some restrictions, you can later move the volumes of a database to a different directory.

 Note — VERSANT does not allow spaces in names, including login and database names.

  

1. Set up database directories and files

Before creating a database, you have to create a database directory, assign access privileges, and create database profile files. You can use the VERSANT makedb utility to create the necessary default setup.

You must create a database directory even if you are going to use UNIX raw devices for the database volumes. The directory contains essential database files, such as the database profile. The database directory must branch from the database root directory as specified during installation of the system software, and it must have the same name as the database that you want to create.

If you want to use UNIX raw devices for database volumes, run makedb, and after creating the raw device, manually set all access privileges. For example, in UNIX, you would use the chown and chmod commands.

If you are recreating a database previously removed with the removedb utility, you can use the old directories and profiles without having to rerun makeprofile or makedb unless you removed the database with removedb -rmdir.

You can set up a database either automatically by using the makedb utility or manually by performing the equivalent steps yourself.

Automatic Setup

To perform an automatic setup of database directories and files, do the following.

A.  Login

If you have write privileges for the home database directory home_db_dir which was created during the installation of the VERSANT software, then login with your user name. If you do not have write access to the databases directory home_db_dir, then login as root.

B.  Run makedb

Create the database directories and files with makedb. The general syntax is:

makedb [options] dbname

If it does not already exist, the makedb utility will create a database directory named dbname per the options in the options parameter, and, if they do not already exist, create database support files. You must run makedb or create a database directory and profile files manually before creating a database with createdb.

For a remote database, append the node name to the database name using the syntax dbname@node.

For options you can substitute:

-g

Group database. The default.

Group databases are accessible to many users at the same time.

 -p

Personal database.

Personal databases are accessible to one application at a time.

 -owner user

Make user the owner of the database directory. The default is to use the current login name.

You can only make someone else the owner if you are logged in as the superuser.

 -cpprofile db

Copy the profile file profile.be from the specified db directory to the directory for the new database.

This option works only if both databases are on the same machine.

If only a database name is used rather than a full path name, the db directory under the database root directory is searched.

 -nofeprofile

Do not create an application process profile.

 -logging

Turn short transaction logging on.

 -locking

Turn short transaction locking on.

 -noprint

Do not display any messages while the command runs.

 The directory created will be:

/dbroot/dbname

A directory for the database that branches from the database root directory. The name of the directory will be the same as the database name specified as dbname.

 Database support files that will be created, if they do not already exist, are:

../.osc/dbname

An application process profile file, located in the .osc directory branching from your home directory. This file contains operating parameters used when this database is a session database.

 profile.be

A database server process profile file, located in the database directory. This file contains database creation and operating parameters.

 .lock

A lock file, which indicates whether or not the database has already been started.

 .dbtype

A database type file, which indicates whether this is a personal or group database.

 For example:

makedb -p my_personal_database

makedb our_group_database

C.  Optionally create UNIX raw devices for the database.

If you want to use UNIX raw devices for the database, you must partition the disk drive and set ownership and access privileges for the raw devices. Also you must edit the server process profile profile.be to specify the raw devices when the database is created.

For example, assume that you have made the following raw device partitions:

/dev/rsh0g

For the System Volume

 /dev/rsh0h

For the Physical Log Volume

 /dev/rsh1b

For the Logical Log Volume

 Then, to assign a user name to the raw devices, use the chown command:

chown username /dev/rsd0g /dev/rsd0h /dev/rsd1b

The specified username must be the user who will create the database and become its database administrator.

For an explanation on how to edit the server process profile profile.be to point to the raw devices, see the "Database Profiles" section.

Manual Setup

If database directories have already been set up, you can run the makeprofile utility to create the application process and server process profile files. The general syntax is:

makeprofile [options] dbname

For a remote database, append the node name to the database name using the syntax database@node.

Options are:

-cpprofile db

Copy profiles from the specified db directory.

If only a database name is used rather than a full path name, the db directory under the database root directory will be used.

 -nofeprofile

Do not create an application process profile.

 -logging

Turn logging on.

 -locking

Turn locking on.

 -noprint

Supress display messages while command runs.

 For example, to make profiles for myDB:

makeprofile myDB

If you are recreating a database previously removed with the removedb utility, you can reuse the directories and profiles without having to run makeprofile or makedb.

  

2. Optionally edit database profile

You have to edit the database server process profile profile.be if you want to change the system volume size from its default value, use raw devices for the database volumes, or alter the default extent size. Parameters for the sizes and names of database volumes cannot be changed after the database has been created.

•     The default name of the System Volume is system, and its default size is 10 megabytes. Edit the sysvol entry in profile.be to change the size of the System Volume.

•     The default name of the Physical Log Volume is physical.log. The default initial size is 2 megabytes. Edit the plogvol entry to change the size of the Physical Log Volume.

•     The default name of the Logical Log Volume is logical.log. The default initial size is 2 megabytes. Edit the llogvol entry to change the size of the Logical Log Volume.

•     The default type for database volumes is files.

•     If files are used for the log volumes, the log volumes expand as needed; the system volume does not change. If you specify a size for the log volumes and the volumes are files, then the parameter will be used to pre-allocate space, but the files will still expand as needed.

•     If you use raw devices for database volumes, you must specify a path name and size for each, because there is no default location for a raw device. If the log volumes are on raw devices they will not extend.

•     The default number of pages per extent on the system volume is 2. To change the number of pages per extent, edit the extent_size entry in the profile.be file.

There are other entries in the server process profile. They are performance related and can be changed before or after creating a database. Performance related parameters are explained in "Manage Database Parameters."

For a standard installation, the default system volume, physical log volume, and logical log volume entries are:

sysvol        10M system
plogvol       2M  physical.log
llogvol       2M  logical.log

The general syntax for each entry is:

sysvol        size [/path/]system
plogvol       size [/path/]physical.log
llogvol       size [/path/]logical.log

...where:

size

The volume size in bytes. Kilobytes can be specified with k or K, and megabytes can be specified with m or M. You can specify any size you want for the volume size.

 /path

The path to the volume. It can be specified in relative or absolute terms. If the first character is /, then the path is absolute. The path for each volume can be different.

 system

Name of the system volume.

 physical.log

Name of the physical log volume.

 logical.log

Name of the logical log volume.

 For raw devices, if you specify a size smaller than the actual raw device, only size space will be used. If you specify a size larger than the actual raw device, the createdb utility will catch the error and raise an exception.

For example, to specify raw devices, a system volume of 40 megabytes, a physical log of 2 megabytes, and a logical log of 5 megabytes:

sysvol       40M /dev/rsd0g

plogvol      2M  /dev/rsd0h

llogvol      5M  /dev/rsd1b

If only volume names are specified in the server process file, VERSANT will use the specifications in the /etc/.oscxxyyzz file or in environment variables to expand the volume names into full path names. The actual name of the .oscxxyyzz file depends on your release, where xx is the major release number, yy is the maintenance release number, and zz is the minor release number. For example, for Release 5.2.4, the file would be .osc050204.

For example, if your database name is dbname and your /etc/.osc050204 file specifies your software root as:

/usr/local/versant

..and your database root is set to the installation default location:

/usr/local/versant/5.2.4/sun4/db

..and you specify your volumes as:

sysvol    40M system
llogvol    2M logical.log
plogvol    5M physical.log

..then the system will expand your entries with the release and platform nodes to

sysvol    40M /usr/local/versant/5.2.4/sun4/db/dbname/system
llogvol    2M /usr/local/versant/5.2.4/sun4/db/dbname/logical.log
plogvol    5M  /usr/local/versant/5.2.4/sun4/db/dbname/physical.log

  

3. Create the database

After setting up the database directories, optionally creating raw devices, setting database access privileges, and optionally editing the server process profile, you can create a database by running the VERSANT createdb utility. The createdb utility will both create the database and update the database system identifier file osc-dbid to register the new database as part of the database system.

The general syntax for createdb is:

createdb [options] dbname

The createdb utility will create, format, and initialize a new database with the name dbname and either make the new database a part of an existing distributed database system or start a new database system. The database name dbname must be unique for the distributed database system it will belong to.

You must be the owner of the database (the database administrator) or the super user to run this utility.

For a remote database, append the node name to the database name using the syntax database@node.

Options that may be specified in the options parameter are:

-i

Reserve space for the system volume.

Reserving space can prevent you from running out of space at runtime. For example, suppose you set the size of the system volume as 100 megabytes in your profile, but you really have only 60 megabytes physically available. In this case, if you use -i, you will immediately get an out-of-space error, but if you do not use -i, you will get an error at runtime as the system volume dynamically expands.

If you have defined multiple storage volumes and the physical space in one volume is less than the logical space, you will get an out-space-error even though there is space available in the next volume.

Pre-allocating space may improve performance, because space will not have to be dynamically allocated. However, pre-allocating space will slow down the process of creating the database, and because the space is used immediately, it will prevent it from being used for other purposes.

The -i option has no effect on UNIX raw devices.

Space for log volumes is always pre-allocated according to the parameters set for the plogvol and llogvol size specifications.

 -noprint

Suppress display messages while running.

 The createdb utility will update the osc-dbid file to register the new database with the existing distributed database system. The file osc-dbid containing the path and name of all databases in the system must be visible from your machine when you run createdb.

Examples of using createdb:

createdb mydb
createdb -i mydb

Components of the newly created database will be:

System volume

A system volume for catalog information and data storage, with a name, location, size, and device according to the specification in the server process profile file profile.be.

The default is a UNIX file of 10 megabytes named system whose location for, say, Release 5.2.4, Sun, and a database named dbname, is:

     /usr/local/versant/5.2.4/sun4/db/dbname/system

Physical log volume

A physical log volume for physical data information related to logging and recovery, with a name, location, size, and device as specified in the server process profile file profile.be.

The default is a UNIX file of 2 megabytes named physical.log whose location for, say, Release 5.2.4, Sun, and a database named dbname, is:

     /usr/local/versant/5.2.4/sun4/db/dbname/physical.log

Logical log volume

A logical log volume for transaction undo-redo information related to logging and recovery, with a name, location, size, and device as defined in the server process profile file profile.be.

The default is a UNIX file of 2 megabytes named logical.log whose location for, say, Release 5.2.4, Sun, and a database named dbname, is:

     /usr/local/versant/5.2.4/sun4/db/dbname/logical.log

.sharemem

A shared memory file, which contains a shared memory identifier.

  

4. Move a database

After you have created a database, you might want to move its volumes to a new disk or a different directory. For example, on a particular machine, you might decide that you want to locate the system software on one disk and the databases on another disk. Or you might want to use the system software on a server while maintaining databases on a local disk.

Caution — You should not move a database after it has been created unless you are an experienced user.

Moving just the data volumes

You can always move the data volumes by editing the system profile file (profile.be), even if you specified an absolute path when you created them. However, this is not true of the system, physical log, and logical log volumes.

To move the data volumes:

1.  Move the data volumes to a new location.

2.  In the server profile file, profile.be, create or change the datavol entry for each data volume you have moved.

See the "Database Profiles" chapter for more information about datavol.

 Moving all volumes

You can create a database and later move all database volumes to a different directory if, before database creation, the volumes were specified in relative terms rather than absolute terms. This can occur in any of three ways:

•     You originally placed the volumes under the database directory.

Even if you specified the location of the database volumes in absolute terms, if they were placed under the database directory, they are internally stored in relative terms... which means that they can be moved at a later time.

 •     You created the database using the defaults.

By default, volumes are stored under the database directory.

 •     Before database creation, you edited the server process profile file in such a way that the volume paths were specified in relative terms.

To move all volumes to a new location, do the following.

1.  Move the database volumes to a new location, preserving their relative relationships.

2.  Reset the location parameter VERSANT_DB to indicate the new database root.

For an explanation of location parameters, see the chapter "Database Directories and Environment."

 

 

 

This online documentation is confidential and proprietary to Versant Corporation and is licensed to you, or to your organization, pursuant to the terms of an agreement between you and Versant that restricts the use of this documentation. Please refer to the agreement for more information or call Versant at 510-789-1500 with any questions.