Design > Persistence

Release Information

Project: PROJECT-NAME
Internal Release Number: X.Y.Z
Related Documents:
LINKS-TO-RELEVANT-STANDARDS
LINKS-TO-OTHER-DOCUMENTS

Overview

TODO: Answer the questions below to help you design the persistent storage aspects of the product. Consider how the reusable sample text relates to your project or prompts you to think of new ideas. Add, edit or delete text as needed.
What are the most important facts that a developer should know about persistent data storage in this system?
The first table to understand is TABLE-NAME. Most other important tables are related to that one. Keep in mind that COLUMN-NAME is not normalized: it actually holds 3 different values in a compressed format previously used by LEGACY-SYSTEM.
The most important things for a new developer to keep in mind are:
  • We have strict referential integrity rules in place that constrain the order of dependent table updates.
  • We never write SQL code in our application source code, we always go through LIBRARY-or-STORED-PROCEDURES.
  • Do not add indexes without first consulting with PERSON-NAME.
Please be aware that we started using LEGACY-TECHNOLOGY, but we are in the middle of a long term transition to NEW-TECHNOLOGY. Tables are being converted one by one.
What are the ranked goals for persistence in this system?
  1. Expressiveness
  2. Ease of access
  3. Reliability
  4. Data capacity
  5. Data security
  6. Performance
  7. Interoperability

Central Database

What is the logical database design?
The logical database design is described in this UML model or this ER diagram.

Additional logical constraints on the database are:

  • A consumer may not review the same product twice, unless it is a subscription product and it has been more than one year since his/her last review.
  • Coupon discount codes were added in an upgrade in 2004. Purchases prior to that date may not have coupon codes.
  • LOGICAL-CONSTRAINT THAT ARE NOT EXPRESSED IN THE DIAGRAM
We do not have a logical database design, we only have a physical database design.
What are the physical tables and views?
The physical database design is described in this UML model or this ER diagram.
The physical database design is described in this SQL file.
The physical database design was built interactively through the database administrative UI and has not yet put under version control. This will be done before MILESTONE.
How will objects in the application be stored in the database?
We will use one database table for each class, and one row in the database for each persistent instance of that class.
We will use a library to do our object-relational mapping. (E.g., torque, Castor, JDO, ADO, hibernate)
What database access controls will be used?
A database user account has been created that has access to the needed application database tables. The username and password for this account is stored in a configuration file read by the application server. The database limits login by that user to only the IP-address used by the application server.
The application uses an existing database user account that has been given the needed permissions. The username and password is stored in a configuration file.
The application uses an existing database user account that has been given the needed permissions. The username and password are entered interactively by the operations engineer when the server is started.
Each end user will supply his/her own username and password to allow the application to connect to the database.
Is this application's central database accessible to other applications?
Yes. The database is an important point of interoperability that will allow new applications to be added later. The database itself provides support for access controls and checks validity constraints so that a defective application cannot corrupt the database.
No. This database should always be accessed through this application. All relevant pieces of information are available through the application interfaces. The database itself does not protect against data corruption that could be caused by other applications.

File Storage

What data needs to be stored in files?
Nothing is stored in files, everything is in the database.
The server stores most data in the database, but product images are written to files on the server hard disk.
All user documents are stored in files on their computer hard disk.
What are the conventions for directory structure and file naming?
N/A, we do not use files.
Files are stored on the server as /var/data/products/imgNNNN-MMM.dat.
Users store files anywhere on their computer, with the filename extension .EXT.
What file system access controls will be used?
N/A, we do not use files.
Files for DATA-ITEM are only readable and writable by the PROCESS-NAME process that runs as operating system user USER-NAME.
Users can use whatever file permissions they prefer: their system security is up to them.
What file format will be used?
The XYZ standard file format.
A java .properties file.
A window's .ini file.
An XML file using this DTD file.
A simple text file with the following format: ...
A custom binary file in the following format: ...

Distributed Storage

What information (if any) is stored on client machines? For how long?
A cookie is stored on the user machine for the purpose of identifying a user session. When the user logs out or closes his/her web browser, the cookie is deleted. Most browsers will not even write this cookie to the disk.
A cookie is stored on the user's computer that is equivalent to their password (but it is NOT actually their password). This cookie is needed for the auto-login feature. The cookie lasts a maximum of 30 days, and it can only be used from the same IP address.
User preferences for shipping method and locale are stored in cookies in their browser. This information is not at all sensitive, so it is kept indefinitely.
All the user data is stored on files on their computers.

Persistence Mechanisms Checklist

Expressiveness: To what extent has this been achieved?
It has been achieved. We have demonstrated that it can handle a complete set of examples.
We think we are doing well. We caught a few cases that we could not express clearly and revised the design.
We should be OK, but we have not reviewed the design for expressiveness yet. That will be done by MILESTONE.
Ease of access: To what extent has this been achieved?
It has been achieved. We have documented some examples of how to access the data and we are happy with them.
We think we are doing well. We plan to access the data in a way that seems easy enough.
We should be OK, but we have not reviewed the design for ease of access yet because we do not know exactly what queries will be needed. That will be done by MILESTONE.
Reliability: To what extent has this been achieved?
It has been achieved. We have designed integrity checks into the database and the libraries that access it.
We think we are doing well. The integrity rules seem pretty straightforward.
We should be OK, but we have not reviewed the design for reliability yet. That will be done by MILESTONE.
Capacity: To what extent has this been achieved?
It has been achieved. We have worked out a formula that estimates storage space needed for a given number of users, products, orders, and BUSINESS-OBJECTS. Our estimates are well under our capacity limits for the first ONE-YEAR.
We think we are doing well. We did a quick review and did not find any obvious capacity problems.
We should be OK, but we have not reviewed the design for capacity yet. That will be done by MILESTONE.
We know that the database will be really slow to UPDATE-or-QUERY once we get past ONE-MILLION records. This design defect is assigned to a developer and is being tracked.
Security: To what extent has this been achieved?
It has been achieved. The database uses very simple and effective controls that are clearly adequate. There are no other ways to access or update the data.
We think we are doing well. The "front door" to the data seems secure. We are not sure if there are any "back door" ways to access or update the data.
We should be OK, but we have not reviewed the design for security yet. That will be done by MILESTONE.
We have known security problems. They are assigned to a developer and are being tracked.
Performance: To what extent has this been achieved?
It has been achieved. We have demonstrated that it can handle a preliminary performance test suite that includes both average case and worst case scenarios.
We think we are doing well. We caught a few operations that clearly would be too slow and we have a review process in place to catch more.
We should be OK, but we have not reviewed the design for performance yet. That will be done by MILESTONE.
We have known performance problems for TYPE-OF-OPERATION. The problems are assigned to a developer and are being tracked.
Interoperability: To what extent has this been achieved?
It has been achieved. We have demonstrated that it can handle a suite of files exported from LEGACY-SYSTEM and our files pass a STANDARDS-BASED VALIDATION-TEST.
We think we are doing well. Preliminary tests pointed out some small problems that have been fixed.
We should be OK, but we have not reviewed the design for interoperability yet. That will be done by MILESTONE.
We still need to do research on the exact formats needed to satisfy our interoperability requirements. Even if we succeed in this release, OTHER-SYSTEM is likely to have a different format next year.
Has the persistence design been communicated to the development team and other stakeholders?
Yes, everyone understands. Feedback is welcome.
No, this is a risk that is noted in the risk management worksheet.
TODO: Check for words of wisdom for additional advice on this template.
Company Proprietary
Copyright © 2003-2004 Method Labs. All rights reserved. License terms. Retain this copyright statement whenever this file is used as a template.