shsql: database tables

SQL database system
| Manual page for database(tables)

## Database tables

shsql stores data in tables.`` Tables may be created using the CREATE TABLE command, and updated using the INSERT, UPDATE, or DELETE commands.`` There are no definition files, etc. that need to be updated when a table is created.`` The only information shsql keeps about a table are its field names, and these reside in the data file field name header. shsql data fields are typeless.``

This manual page discusses standard database tables.`` In addition to these shsql can also store and use data in temporary tables and ordinary files.`` Also, shsql allows database tables to be organized hierarchically.`` See also the shsql table types chart where these table types are compared.``

## Security concerns

Because shsql allows any readable file on your file system to be accessed, avoid situations where table names are built using user-supplied values (such as CGI user variables).. this might allow a hacker to see arbitrary files.``

## Fields

shsql tables contain one or more fields (sometimes called columns in relational parlance). Fields are specified in the `CREATE TABLE` command.`` To see the names of all fields in a table, the tabdef(1) command may be used. The SQL ALTER TABLE command can be used to add or remove fields after a table has been created.``

## Naming

Table names and field (column) names are case sensitive, max length 30 characters, may not contain any white space or punctuation character other than underscore (_), and must begin with an alphabetic character.``

## Data types

shsql uses no data types. All fields are considered alphanumeric.`` Fields that need to be handled numerically require that the keyword NUMERIC be given in an ORDER BY or CREATE INDEX command.`` Dates (etc.) may be stored directly if using notation that sorts naturally (such as YYYY/MM/DD) , otherwise dates must be converted to a numeric equivalent (such as Julian) before reaching shsql.``

## Importing data into a shsql table

Because it uses simple `ASCII` files, shsql has no formal "import" or "bulk load" facility. If you have a file that is to become a shsql table, be sure it conforms to the table structure specification, including a field name header.`` CREATE TABLE should not be used in this case.``

## Table file structure

Database tables are stored as plain `ASCII` text files.`` These files are located in the database `data` directory.`` Table files conform to these specifications:

- `ASCII` text, one record per line, each record terminated by a newline character.``
- Any line beginning with `//` is taken as a comment and skipped.``
- Within a record are one or more fields. Fields are whitespace-delimited.`` Whitespace means any combination of one or more spaces or tabs.`` Records that shsql writes (INSERT, UPDATE, SELECT INTO, etc) have space-delimited fields by default. If you want to maintain tab-delimited data files, dbdelimchar should be set to `tab` in your config file.``
- The first non-comment line in the file must contain the field names, each separated by whitespace.``
- Embedded whitespace characters are represented in the data file using underscore characters. shsql performs the conversion transparently.``
- Additional whitespace characters may be located at the end of a record for padding (so that future updates can use the same space even if a little bigger).``
- Some lines may contain nothing but whitespace characters. shsql does this to erase records that have been deleted or moved.``
- Individual fields cannot be longer than 255 characters; lines cannot be longer than 3000 characters; maximum of 80 fields per table. These limits are defined in `shsql.h`.``

You can create a database table manually simply by creating a file that conforms to these specifications; you don't have to do a `CREATE TABLE`.``

## Manually editing data table files

shsql data tables can be edited manually by the database owner using the dataedit(1) utility.

Warning! Never edit data files directly in an active database without using dataedit(1) or some other process that interfaces with shsql's file locking scheme.`` Other processes won't know the table is being modified and corrupted data could result.``

Warning! Care should be exercised during manual editing. Valid table structure must be maintained.``

dataedit(1) manages the file locking, then invokes your favorite text editor based on the `EDITOR` environment variable. When you're done editing, it will check for any indexes associated with the table, since these will likely need to be rebuilt.``

## Manually creating data table files

Tables can be created manually instead of using SQL `CREATE TABLE`. In your database `data` directory, create a file using the same name that you want for your table.`` The first line in the file should contain all of the field names, separated by a space (or whatever your delimiter character is). This line should terminate with a newline. This will be the field name header for the table.`` Save and you're done. Locking shouldn't be an issue because presumably there is no code trying to access the new table yet.``

## Reading table files by other programs

Data files can generally be accessed at any time for reading by any desired program.`` You may want your program to check to be sure the file isn't read-locked before reading.``

## Updating table files by other programs

shsql data tables can be created or updated by other programs. Use the dataedit(1) utility to invoke the command. It will automatically handle locking and rebuilding of any indexes. Valid table structure must be maintained.`` See also the warnings in the Manual Editing section above.``
Copyright Steve Grubb

Markup created by unroff 1.0, `` `` June 02, 2005.