Installing on UNIX systems

Before you begin, make sure you have copied your dbCGI executable to your cgi-bin (or equivalent) directory.

The simplest use of dbCGI

The easiest way to use dbCGI is to use a URL that includes both the dbCGI executable and the file name of a dbCGI file. The dbCGI file name must end with .sql.

Example: A URL using dbCGI for Postgres to process the file filename.sql which is in your top level HTTP documents directory:

http://www.example.com/cgi-bin/pgdbcgi/filename.sql

A better approach

Alternatively, if you are using Apache, you can define the dbCGI executable to be the handler for "sql" files. (See the "AddHandler" facility in the HTTP server's configuration files). If you do this, you can omit the "cgi-bin/xxxdbcgi" sequence. Additionally, users won't be able to view the dbCGI source files.

Example of the configuration file lines:

AddHandler run-dbcgi .sql Action run-dbcgi /cgi-bin/sybdbcgi

Example URL with this configuration:

http://www.example.com/filename.sql

An even better approach

The best approach involves writing your dbCGI application to take advantage of Apache's URL rewriting capability. Create a directory in your HTTP documents directory to contain your application, and add a .htaccess file like the following:

RewriteEngine on
RewriteBase /~troy/my-dbcgi-app
RewriteRule ^(.*)$ /cgi-bin/pgdbcgi/my-dbcgi-app/app.sql?$1

The file app.sql would contain something like:

<sql noheader/>%[*appdir:/path/to/application/files%]<sql include>%[=appdir%]/start.sql</sql>

Then start.sql will contain directives that interpret the query string and pass control to other dbCGI files:

<sql quiet>
  <sql foreach action/>
  <sql foreach qs/>
  <sql foreach contenttype/>
  <sql foreach cmd/>
  <sql foreach args/>

  <sql set contenttype>'text/html'</sql>
  %[*qs:%[$QUERY_STRING%]%]
  <sql set cmd>  qs \\ '/' </sql>
  <sql if>
    <sql-if evaluate>  ?qs > ?cmd  </sql-if>
      <sql set args> qs $ (?qs - ?cmd - 1) </sql>
  </sql>
  <sql foreach qs/>

  <sql if>
    <sql-if evaluate>
      cmd = "" |
      cmd = "main"
    </sql-if>
      <sql set action>"mainpage"</sql>

    <sql-if evaluate>
      cmd = "showlist" |
      cmd = "additem"
    </sql-if>
      <sql set action>cmd</sql>
  </sql>    
</sql>Content-Type: %[=contenttype%]

<sql include>%[=action%].sql</sql>

Using this technique you can put all of your important files outside of the HTTP documents tree, so your files are more secure from prying eyes. Installing your application on a new system will be easier because the only files that need installation into and modification in the HTTP documents directory are the .htaccess and app.sql files.