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.
For information about managing database connections to improve performance, see
Managing database connections.
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.
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. | 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).
| |
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).
|
Configure the DBMS client software on the SilverStream Server machine. | Use native database software (for example, Oracle SQL-Net, Microsoft SQL Server client, Informix CLI, and so on). | |
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.
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.
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."
This section describes how the SilverStream Server connects to a database.
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.
SilverStream can access databases through a native Java Database Connectivity (JDBC) driver or through a JDBC-ODBC bridge driver.
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.
There are four types of JDBC drivers.
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.
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.
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.
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.
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 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.
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.
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.
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.
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:
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.
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).
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. | |
(Read-only) The combination of a JDBC driver and SilverStream-specific files to use to connect to the database. | |
(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. | |
(Read-only) Any extra attributes to set for the driver. The syntax is driver-specific. See your driver documentation for more information. | |
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.
| |
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.
| |
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 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.
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:
This section describes administration tasks you may need to execute from time to time. For regular database maintenance, consult your database vendor's documentation.
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.
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.
SilverStream supports several important database administration procedures. For more information about these procedures, consult your database vendor's documentation.
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:
