ZDB
Here's a quick link to the main tarball download. See the bottom of the page for further downloads. I recommend you read the material on this page before attempting to use the database, although most of this information is duplicated in the README file inside the download.
Introduction
The ZDB (Zazzybob.com DataBase) can be used to maintain simple lists and databases (such as telephone directories, address lists, etc). It implements mechanisms for basic queries and reporting, and also allows us to join two tables by a primary key, and display query results based thereon.
ZDB is not a relational database. If you want a relational DB then use a proper DBMS!
ZDB is, however, highly useful for small, non-critical database needs, especially where "flat-files" are all that's really required, but where maintaining a long list of data manually would be too labour intensive.
ZDB requires the "usual-suspects" with regards to tool dependencies. All of the required tools will be present in any modern UNIX/Linux system. The scripts are implemented as bash scripts, but if you change the shebang line to match the path to your shell, and as long as your shell supports the ((...)) arithmetic construct, you'll be okay! There aren't any bash-specifics in the scripts.
Some of the scripts (especially query scripts) may run fairly slowly depending on your system. There is a lot of data processing going on in the background (involving many invocations of awk!). On a P4 2.66GHz the results will be instantaneous, whereas on a PII 233MHz you might not be so lucky.
Package Contents
The ZDB package consists of the following scripts:
- zdb_constants
- Contains constants needed by all scripts
- zdb_create_table
- Creates a new table
- zdb_insert_values
- Insert values into a table
- zdb_join_tables
- Query two tables using a join
- zdb_remove_table
- Drop a table
- zdb_remove_values
- Remove values from a table
- zdb_select_all
- Display an entire table
- zdb_select_rows
- Query a table by row
- zdb_select_values
- Query a table by column name
- zdb_get_by_key
- Get a single row by it's key value
Also included in the download is zdb_test which is an example showing how each of the commands is used, creating tables, inserting values, querying the tables, and finally deleting the tables.
As you can see, I haven't implemented a "change row" script. I don't see the point, as it would just duplicate the functionality of a call to zdb_remove_values followed by a call to zdb_insert_values. I have shown an example of this in the zdb_test script, included with the download.
Overview of Data Structure
Each table is made of two parts. A .def (Definition) file, and a .dat (Data) file. The .def file is created when the table is first created, and contains a list of all the column names in that table, and thus, provides that tables definition. The .dat file is created when the first row of values is inserted (and is deleted when the last row of data is removed). This is a flat file using ":" as a column delimeter. Therefore, do NOT use ":" in any of your data!
The idea of the .def file is to provide column name to field position translation, so that we can query in the form column_name=value (kind of like a WHERE clause in SQL). They are saved as table_name.{dat,def} in the directory specified by the ZDB_DIR constant (see below).
The first (left-most) column in each table is considered to be it's key and must be unique for each row in the table.
Syntax
The syntax of each command is discussed below.
zdb_constants
- Syntax
- N/A
In the current implementation, this script contains only one constant, ZDB_DIR, which is the full path to the directory containing your database (.dat/.def) files. It is important that the directory exists, and that this constant is set correctly to reference the directories path, otherwise nothing will work!
- Example
- ZDB_DIR=/home/kevin/databases/db_one
zdb_create_table
- Syntax
- zdb_create_table table_name col_1 [ col_2 ... col_n ]
Create a table within ZDB_DIR named table_name as specified by the first argument to the command. The column names are specified by subsequent arguments to the command. At least one column must be specified. This command creates a file in ZDB_DIR named table_name.def.
- Example
- zdb_create_table my_table id f_name s_name t_name
zdb_insert_values
- Syntax
- zdb_insert_values table_name val_1 [ val_2 ... val_n ]
Insert values specified by val_1, etc, into table_name. This has various error checking mechanisms implemented, and will check for the correct number of values (i.e. the same number of values as there are columns in the table). val_1 in the left-most column is considered to be a primary key for that row of data, and must be unique within that table. Values are added sequentially, and are thus "appended" to the table in the order that they are added. No sorting takes place. If any single value contains spaces, it must be quoted, e.g. "example value with spaces".
- Example
- zdb_insert_values my_table 1 Kevin Waldron 0208-111-1111
zdb_join_tables
- Syntax
- zdb_join_tables table_one table_two [ searchterm | col=searchterm ]
Join two tables by their key field, and print fields from both tables where the row key matches. Other rows are not printed. An optional searchterm can be specified. This searchterm MUST be a single word, and can be of the form "searchterm" where all fields are searched, or "col=searchterm" whereby only the specified column name "col" is searched.
- Example
- Suppose we have two tables populated with data, the following session depicts command usage and possible output
id name number data_1 data_2
1 Kevin Smith 02081111234 zdb_data more_data
2 Kevin Jones 02078392111 data_value more_data
68 Mr Kevin 9230192912 0291 19192
zdb_remove_table
- Syntax
- zdb_remove_table table_name
If table_name exists, both it's .def and .dat files will be deleted.
- Example
- zdb_remove_table my_table
zdb_remove_values
- Syntax
- zdb_remove_values table_name key
Removes the row from table_name specified by key, where key is the unique identifier for that row (the entry in the first column of the table for that row).
- Example
- To remove the row with key "4" from my_table
- zdb_remove_values my_table 4
zdb_select_all
- Syntax
- zdb_select_all table_name
Displays all data from table_name preceeded by a header row detailing the column names
- Example
- zdb_select_all my_table
zdb_select_rows
- Syntax
- zdb_select_rows table_name searchterm|col=searchterm
Shows all rows from table_name where searchterm can be found. Accepts both forms of searchterm specification, as discussed in the zdb_join_tables section above.
- Example
- zdb_select_rows my_table Kevin
zdb_select_values
- Syntax
- zdb_select_values table_name col_1 [ col_2 ... col_n ]
Selects and displays all data from the specified columns in table_name
- Example
- Yes, multiple instances of the same column can be specified, to repeat their output
- zdb_select_values my_table f_name f_name s_name
zdb_get_by_key
- Syntax
- zdb_get_by_key table_name key
Select only the single row from table_name that has the unique key key.
- Example
- zdb_get_by_key my_table 1
Bugs, Etc
I have no doubt that you will find some quirks with these scripts, after all this is the initial (v0.1) release! Please contact me with any comments, suggestions and bugfixes.
Downloads
Full source code and README file zdb.tar.gz
