Administrator's Guide

Chapter 4   Database Configuration

This chapter describes how to set up a database for use with the SilverStream Server and how to configure a database that has been added to the server.

It contains sections on:

    For information about managing database connections to improve performance, see Managing database connections.

Setting up a supported database   Top of page

SilverStream uses databases to store the components of SilverStream applications including pages, forms, views, and business objects. You make a database available to SilverStream from the SilverStream Designer or by using SilverCmd. When you add a database, the SilverStream Server adds system tables to each application database. SilverStream uses these system tables to store your application code, Java classes, SilverStream metadata, and so on.

The SilverStream Server can communicate with multiple database engines at the same time. For example, you can install your SilverMaster database on Sybase Adaptive Server Anywhere and have all of your application databases in another database, such as Oracle.

Setting up the database   Top of page

SilverStream can access an existing database containing data and any new databases that you create. Creating new databases on most DBMSs in corporate environments is a function done by a DBA (database administrator). If you are in such an installation you may require the DBA's assistance creating new databases or changing user access rights for SilverStream to access these databases. If you are running a DBMS locally, you will be able to accomplish these DBA tasks without assistance.

The following table describes the general tasks that you need to perform to set up a database that SilverStream can access.




Set up a database user account that the SilverStream Server will use to connect to the database.

Your DBA if you have one.

DBMS utility for adding and modifying database account permissions (for example, Sybase Central, Microsoft Enterprise Manager, Oracle Server Manager, Informix Control Center, and so on).

    For more information, see Setting up database accounts.

Set up an ODBC data source for any new database and any existing databases you want SilverStream to use through an ODBC bridge.

A system administrator, if set up as a system resource. Otherwise, by a developer.

ODBC control panel (Windows only; ODBC connections are currently not supported on UNIX).

    For more information, see the ODBC chapter in the Installation Guide.

Configure the DBMS client software on the SilverStream Server machine.

Your DBA, if you have one.

Use native database software (for example, Oracle SQL-Net, Microsoft SQL Server client, Informix CLI, and so on).

Install the JDBC driver.

DBA or system administrator, if you have one.

Use native DBMS installer to install a JDBC driver on the SilverStream Server machine (for example, jConnect).

    For information about how to set up your specific database type for use as a SilverMaster or as an application database with SilverStream, see the appropriate configuration chapter in the Installation Guide.

Setting up database accounts   Top of page

Once you have created the database, you need to set up a database account for SilverStream to use to connect to each database. All database access in an application is through the SilverStream Server; clients do not access the databases directly.

You should set up a different account for your SilverMaster and for each application database so you can easily tell which applications are hitting your database when and how often, and you can more easily troubleshoot performance problems.

When setting up a database, make sure the user account (for example, Agsmith) has CREATE TABLE, INSERT, UPDATE, and DELETE permissions.

Communicating with the SilverStream Server   Top of page

Once you have created the database and configured it as described in the Installation Guide, you simply add it to the SilverStream Server.

NOTE   When adding an application database on a UNIX platform, you must add the location of the database to the AGCLASSPATH environment variable, then restart the server before you can add the database. For information about AGCLASSPATH, see Setting the AGCLASSPATH variable.

When adding a database to the server, you can optionally store the system tables in a separate database than your application (data) tables. (But note that you cannot store the system tables in the SilverMaster database.)

If you choose to store the system tables separately, just remember to back them up. Storing the system tables separately is a useful option if you already have other applications accessing a production database and you do not want to change the database structure, or if the SilverStream Server is accessing multiple databases. If you choose to store your SilverStream system tables separately from your application's tables, you should set up unique database accounts for each of these "shadow databases."

SilverStream database configuration   Top of page

This section describes how the SilverStream Server connects to a database.

Supported databases   Top of page

A supported database is a database that can be recognized by, and can interact with, the SilverStream Server.

SilverStream supplies a small driver for each supported database. This driver handles any database-specific capabilities, such as some Data Definition Language (DDL) syntax for CREATE TABLE and ALTER TABLE, as well as certain Data Manipulation Language (DML) calls.

    See the release notes for the complete list of supported databases.

Each database used by SilverStream needs some system tables. For a listing of these tables see SilverStream System Tables and URLs. These are ordinary database tables reserved for SilverStream use, and they can be added to your application database or stored in a separate database. If you store them separately, remember to back them up periodically.

Database access   Top of page

SilverStream can access databases through a native Java Database Connectivity (JDBC) driver or through a JDBC-ODBC bridge driver.

Java Database Connectivity (JDBC)

JDBC is a standard Application Program Interface (API) for allowing Java applications such as the SilverStream Server to enable SQL access to relational databases. The application makes JDBC calls to the JDBC driver, which translates the calls to the API of the underlying database. JDBC drivers exist for a number of commonly used relational databases. The Java runtime system supplies an ODBC bridge driver, which allows JDBC to connect to supported databases through an ODBC driver.

Only the SilverStream Server accesses the database. Clients communicate through the SilverStream Server for database access.

JDBC access

There are four types of JDBC drivers.

JDBC driver


JDBC-ODBC bridge (Type 1)

For databases that support ODBC.

JDBC to a database vendor DLL (Type 2)

Supplied by the vendor or by third parties.

JDBC to middleware software to the database (Type 3)

Not recommended for use with SilverStream.

Pure Java to a network protocol (Type 4)

This is the best driver to use with SilverStream, because it works directly with the network protocol. However, only a few databases currently have Type 4 drivers available.

JDBC drivers exist for many current databases such as Oracle and Microsoft SQL Server, with more being developed. Integrated drivers are available from third parties for Sybase Adaptive Server Enterprise, DB2, and Informix.

The SilverMaster database catalog   Top of page

SilverStream relies on a master database catalog called the SilverMaster for overall system management. This database is created during installation.

You can use any supported database to create the SilverMaster catalog, as long as it supports auto-incrementing columns. For convenience, during installation in NT (unless you specify otherwise) the SilverMaster is created as a Sybase Adaptive Server Anywhere database (Adaptive Server Anywhere comes with your SilverStream Windows package). If you are installing on another operating system, you can create your SilverMaster using any supported database on that operating system.

    For information about troubleshooting the SilverMaster database, see Using the SilverMasterInit program.

SilverMaster functions   Top of page

The SilverMaster catalog provides overall system management, including the following:

The SilverMaster catalog contains internal SilverStream tables used for system management. These tables are reserved for SilverStream use. For a list of these tables, see SilverStream System Tables and URLs.

NOTE   SilverStream advises against storing unrelated (user data) tables in the SilverMaster catalog.

Data access and queries   Top of page

This section describes how SilverStream data source objects access data and how database queries are handled by the SilverStream Server.

    For more complete information, see the data access chapter in the Programmer's Guide.

Data source objects   Top of page

SilverStream provides a server-side object called a data source object. This object allows developers to take full advantage of SilverStream's code for managing result sets in a three-tiered environment. Developers can use a data source object (DSO) by handing it a result set on the server. The SilverStream Server then makes that result set available via an object interface on the client. Communication between client and server happens automatically, with data being passed to the client in 100-row increments as needed. Data is cached on both the client and server.

The DSO allows automatic data binding, meaning that on the client, developers can bind data-aware controls such as text boxes, list boxes, and drop down lists to the columns of a DSO without writing code.

DSOs can be used for handling stored procedures and complex SQL commands. They can also make data not stored in relational sources (such as SAP, Peoplesoft, or Notes) accessible within SilverStream applications, and appear to SilverStream developers as if they were relational tables.

JDBC and SilverStream queries   Top of page

JDBC allows a program to pass query strings to a supported database. The database to which you pass a query must be JDBC-compliant. This means that the database must have at least the functionality of ANSI SQL92 Entry Level. All the SilverStream-supported databases are at this level of standardization.

The SilverStream client does not pass SQL statements to the SilverStream Server for execution. Instead, the client passes row selection and ordering information to the SilverStream Server as SilverStream expressions. The server combines this information with other information built by the Page, Form, View, Business Object, or Table Designers and dynamically constructs the SQL, which it then passes to the database through JDBC for execution.

Connecting to the database   Top of page

This section describes how to add a database to the SilverStream Server, how to modify the properties of an existing database, and how to delete a database.

Adding a database

When you add a database to the SilverStream Server, an entry is made in the SilverMaster database catalog so that SilverStream knows about the database. (Adding a database in SilverStream does not create a new database; it simply makes a pre-existing database known to the server.)

You add a database to the server from the Main SilverStream Designer or from the command line using SilverCmd.

    For more information, see Adding a database in the Main Designer chapter or AddDatabase in the SilverCmd Reference in the online Tools Guide.

Modifying database properties

If you want to modify the properties of a database you have added to a server, select the Databases panel in the Configuration options in the SilverStream Management Console, then select the database name from the list. Use the resulting form to change any of the database properties.

    For more information, see Configuring the database.

Removing a database

If you don't need to maintain a connection between a database and the SilverStream Server, you can remove the connection.

To remove a database connection with the server:

  1. Select the database in the SilverStream Designer.

  2. Do either of the following:

What happens

When you remove a database from the server, SilverStream removes the entry from SilverMaster but leaves the database itself fully intact (including the SilverStream system tables).

Using the command line

You can also remove a database connection from the command line using SilverCmd.

    For more information, see RemoveDatabase in the SilverCmd Reference in the online Tools Guide.

Configuring the database   Top of page

The SilverStream Management Console allows you to configure databases that have been added to a server. Use the SMC when you want to change the existing database user or configuration information. You originally set this information either during installation or when you added a new database.

You can also use the SMC to synchronize database information, delete idle connections, and get information about the separate database containing SilverStream system tables (if you chose to store the SilverStream system tables in a different database than your application database).

To configure a database:

  1. Invoke the SMC.

  2. Select Configuration options.

  3. Select the Databases panel.

  4. Select the database name from the dropdown list.

  5. Use the table below to enter the information for the database:



    User name and password

    A user name and password pair, which the SilverStream Server can use for a database user connection to your database.

    This user name must already be known to the database and have the appropriate read/write permissions.

    Database platform

    (Read-only) The DBMS.

    Driver set

    (Read-only) The combination of a JDBC driver and SilverStream-specific files to use to connect to the database.

    JDBC driver

    (Read-only) The fully qualified name of the JDBC driver to use when connecting to the database.


    (Read-only) The fully qualified package name of your JDBC driver class (the database URL). The driver uses it to connect to the database. The URL is driver-specific. See your driver documentation for more information.

    JDBC URL attributes

    (Read-only) Any extra attributes to set for the driver. The syntax is driver-specific. See your driver documentation for more information.

    Synchronize Database Schema

    A button that lets you synchronize the database. SilverStream may not be the only tool you use to modify your database's schema. For example, you may be using Sybase Central to modify your Sybase Adaptive Server Anywhere database structure outside of SilverStream. SilverStream keeps its own image of the database schema.

    Click this button to update an existing SilverStream database structure with any structure changes that may have occurred through another tool.

        For more information about this option, see Synchronizing database schema.

    Delete Idle Connections

    Release database connections that are not currently being used. When the server needs more connections, the connection pool will automatically regrow as needed to the maximum number of connections defined. Deleting idle connections allows you to (at least temporarily) free up some database connections for use by other applications without having to restart the server.

        For information on permanently changing the pool size, see Setting the maximum and minimum number of database connections.

    System Database Properties

    A button that displays only if the selected database is storing its SilverStream system tables in another database (you specify this property when adding a database to a server).

    Click this button to see information about the database storing SilverStream system tables for the selected database on the server.

        For more information about storing system tables externally, see Adding a database in the online Tools Guide.

    For more information about the Database Platform, Driver Set, JDBC Driver, JDBC URL, and JDBC URL Attributes fields, see Adding a database in the online Tools Guide.

    For information about setting the maximum and minimum number of database connections on this panel, see Setting the maximum and minimum number of database connections.

Synchronizing database schema

This option synchronizes the server metadata and the current database schema, to ensure that tables, views, and key definitions cached on the server match the current database structure. The server metadata and the current database schema most commonly get out of synch when changes are made to the database by tools other than the SilverStream Designer.

SilverStream checks for the following types of changes:

When the server starts up, it checks for database consistency.

NOTE   You can prevent the server from checking database consistency with the -nodbcheck command-line option. You can also use the -noexitondbcheck command-line option to see any errors while still starting the server. If you see any errors you should synchronize the database. For more information, see Database not synchronized.

When it receives a request to synchronize the database, the server does the following:

General database administration   Top of page

This section describes administration tasks you may need to execute from time to time. For regular database maintenance, consult your database vendor's documentation.

Moving the SilverMaster database   Top of page

If you move your SilverMaster database from the server it was initially installed on, the SilverStream Server needs to know the new connection location. For example, if you decide to upgrade your server, you may want to move your SilverMaster to the new machine. The easiest way to update SilverStream about a moved SilverMaster is to rerun the SilverStream Installation program after you have moved your SilverMaster database and modified settings specific to your DBMS.

NOTE   Some databases require that you update connection parameters (for example by using ODBC, JDBC, or Oracle TNS).

In the SilverStream Installation program, specify the moved SilverMaster database as you respond to the prompts. Be sure to choose the following option: Install a new Server configuration file from the screen that runs SilverMasterInit. It is not necessary to run SilverMasterInit. If you run SilverMasterInit to initialize the SilverMaster properties, you will have to rerun the license install, recreate any SilverStream users/groups, and manually add your SilverStream application databases. It is a good idea to verify the new SilverMaster database connection, using another application, before restarting the SilverStream Server.

Moving an added database   Top of page

If you have moved a database that you have added to the SilverStream Server, remove the database from the server, then re-add it to the server.

    For more information, see Adding a database in the online Tools Guide.

Database-level administration   Top of page

SilverStream supports several important database administration procedures. For more information about these procedures, consult your database vendor's documentation.

Backing up the database

A SilverStream system table can be backed up like any other table in your database and by using the same utility. If you store SilverStream system tables separately from user data, make sure that you back them both up when you back up the database. SilverStream system tables can get out of sync with the database structure if one is restored but the other is not.


SilverStream stores all application information (including SilverStream metadata, such as pages, forms, views, and scripts) in a relational database, so you can use the standard replication features of your native database. Replication involves the synchronization, duplication, and distribution of a database. You might replicate a database for the following reasons:

Copyright © 2000, SilverStream Software, Inc. All rights reserved.