-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathschema.html
More file actions
268 lines (266 loc) · 9.86 KB
/
schema.html
File metadata and controls
268 lines (266 loc) · 9.86 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<title>exedio persistence - Schema Trail</title>
<meta name="keywords" content="Persistence, Java">
<meta name="description" content="persistence framework for java">
<link rel="stylesheet" href="cope.css">
<style type="text/css">
img.console
{
border:0;
margin:12pt;
}
</style>
</head>
<body>
<!-- HEADER -->
<div id="header_wrap" class="outer">
<header class="inner">
<a id="forkme_banner" href="https://github.com/exedio">View on GitHub</a>
<h1 id="project_title">exedio persistence</h1>
<h2 id="project_tagline">Persistence Framework for Java.</h2>
<a id="toplink" href="index.html">Go to top</a>
</header>
</div>
<!-- MAIN CONTENT -->
<div id="main_content_wrap" class="outer">
<section id="main_content" class="inner">
<h2>Schema Trail</h2>
<p>
The <a href="webapplications.html#console">exedio console</a>
gathers various runtime information around the framework,
such as cache statistics, connection pool, jdbc driver etc.
This trail highlights it's schema evolution capabilities.
It assumes that you have already deployed the <i>exedio console</i> into your
web application.
</p>
<h3 id="contents">Contents</h3>
<ul>
<li><a href="#inspection">Inspection</a></li>
<li><a href="#modification">Modification</a></li>
<li><a href="#revision">Revision</a></li>
<li><a href="#further">Further Reading</a></li>
</ul>
<h3 id="inspection">Inspection</h3>
<p>
You may want to know first,
which database schema is created by the framework.
Open up the Console in your browser,
select the Tabulator <i>Schema</i>,
and you will see something like this:
</p>
<img src="schema1.png" alt="Console Screenshot 1" class="console" width="500" height="51">
<p>
The example model used to create this screenshot
contains two types <code>Customer</code> and <code>Order</code>.
Lets say, type <code>Customer</code> looks like this:
</p>
<pre>
public class Customer extends Item
{
static final StringField email = new StringField().<a href="api/com/exedio/cope/StringField.html#unique()">unique</a>();
}
</pre>
<p>
Now click on the table <i>Customer</i>
to see the table details:
</p>
<img src="schema2.png" alt="Console Screenshot 2" class="console" width="500" height="75">
<p>
This shows you two columns:
</p>
<ul>
<li>
An integer column <code>this</code>
holding the primary key for implementing object identity.
</li>
<li>
A string column <code>email</code> holding the value of
the field <code>email</code>.
</ul>
<p>
Following the columns there are the details of database constraints
set up by the framework,
but we won't deal with them in this trail.
</p>
<h3 id="modification">Modification</h3>
<p>
Let's say you want to add a new field to your type:
</p>
<pre>
public class Customer extends Item
{
static final StringField email = new StringField().<a href="api/com/exedio/cope/StringField.html#unique()">unique</a>();
<b>static final BooleanField blocked = new BooleanField();</b>
}
</pre>
<p>
If you want to adjust the database schema
without loosing all your data,
you have to issue some SQL like
<code>alter table Customer add column blocked integer</code>.
The framework can do that for you,
but much more comfortable.
</p>
<p>
If you start up the new application containing the new field,
the <i>Schema</i> looks like this:
</p>
<img src="schema3.png" alt="Console Screenshot 3" class="console" width="500" height="54">
<p>
The red color tells you,
something is wrong with table <i>Customer</i>.
Click on it for further details:
</p>
<img src="schema4.png" alt="Console Screenshot 4" class="console" width="500" height="100">
<p>
Again, the red color tells you,
that something is wrong with column <i>blocked</i>.
In fact it is just missing, as expected.
At the end of the line there is a checkbox named <i>create</i>.
Select it (already done in this screenshot)
and push the button <i>Apply</i> further up the page.
The next screen looks like this:
</p>
<img src="schema5.png" alt="Console Screenshot 5" class="console" width="500" height="101">
<p>
Column <i>blocked</i> does exist now,
and therefore the red background turned to green.
On the same page the sql statement sent to the database
is logged:
</p>
<img src="schema5a.png" alt="Console Screenshot 5a" class="console" width="500" height="59">
<p>
In a similar way you may deal with dropped columns,
changed column types, new tables, changed constraints etc.
It's recommended to check for red color
in the <i>Schema</i> tab,
whenever deploying a new version of your application
on an existing database schema.
If everything is green, then there is a very little chance,
that application and database schema don't fit to each other.
</p>
<h3 id="revision">Revision</h3>
<p>
Now that you have some sql for revising your database
to the new application version,
you may want to reuse it for two purposes:
</p>
<ul>
<li>Communicate it to your coworkers, so they can adapt their database,
once they check out your modification from the source code repository.</li>
<li>If there is already any production system, apply it to it,
once your modification is deployed there.</li>
</ul>
<p>
With <i>Revisions</i> both is achieved easily.
All you have to do is to register the sql command at the model
of your application.
The model currently looks like this:
</p>
<pre>
static final <a href="api/com/exedio/cope/Model.html">Model</a> model = new <a href="api/com/exedio/cope/Model.html#<init>(com.exedio.cope.Type...)">Model</a>(
Customer.TYPE,
Order.TYPE);
</pre>
<p>
Now insert a list of revisions with the first revision
containing your sql command:
</p>
<pre>
static final <a href="api/com/exedio/cope/Model.html">Model</a> model = new <a href="api/com/exedio/cope/Model.html#<init>(com.exedio.cope.Revisions,com.exedio.cope.Type...)">Model</a>(
<b>new <a href="api/com/exedio/cope/Revisions.html#<init>(com.exedio.cope.Revision...)">Revisions</a>(
new <a href="api/com/exedio/cope/Revision.html#<init>(int,java.lang.String,java.lang.String...)">Revision</a>(1, "add flag blocked to customer",
"alter table Customer add column blocked integer")
),</b>
Customer.TYPE,
Order.TYPE);
</pre>
<p>
So your sql command is executed,
whenever your application starts up on a database,
where revision 1 has not yet been applied.
So this happens both on the systems of your coworkers
and on the production system as well without any further action needed.
</p>
<p>
Of course you can have more than one revision,
and each revision can consist of more than one sql command.
Below the date of last modification is added to both types:
</p>
<pre>
static final <a href="api/com/exedio/cope/Model.html">Model</a> model = new <a href="api/com/exedio/cope/Model.html#<init>(com.exedio.cope.Revisions,com.exedio.cope.Type...)">Model</a>(
new <a href="api/com/exedio/cope/Revisions.html#<init>(com.exedio.cope.Revision...)">Revisions</a>(
<b>new <a href="api/com/exedio/cope/Revision.html#<init>(int,java.lang.String,java.lang.String...)">Revision</a>(2, "log last modification",
"alter table Customer add column lastModified date",
"alter table Order add column lastModified date"),</b>
new <a href="api/com/exedio/cope/Revision.html#<init>(int,java.lang.String,java.lang.String...)">Revision</a>(1, "add flag blocked to customer",
"alter table Customer add column blocked integer")
),
Customer.TYPE,
Order.TYPE);
</pre>
<p>
However, before you really can start with revisions,
you have to do two one-time preparations:
</p>
<ol>
<li>
Make sure, that Model.<a href="api/com/exedio/cope/Model.html#revise()">revise</a>()
is called before you use the application.
This method actually executes the sql commands when necessary.
The best place for this call is immediately after
<a href="api/com/exedio/cope/Model.html#connect(com.exedio.cope.ConnectProperties)">connecting</a>.
If you already use the
<a href="api/com/exedio/cope/misc/CopeFilter.html">CopeFilter</a>,
you don't have do do anything, the filter calls Model.revise() for you.
</li>
<li>
exedio persistence stores the information about revisions already applied to
the database schema in an extra table named '<code>while</code>'.
Create this table with the <i>exedio console</i>,
and make sure, this is done on the production system and the systems
of your coworkers as well.
It will be the last time, you have to do something like this manually.
</li>
</ol>
<p>
exedio console also shows information about revisions
and their execution on the database currently used.
</p>
<h3 id="further">Further Reading</h3>
<p>
After having a look at the exedio console,
you may want to go back to exedio persistence itself.
</p>
<ul>
<li>
<a href="searching.html">Searching Trail</a>
gives you an introduction into the searching capabilities of exedio persistence.
</li>
<li>
<a href="fields2.html">Field Reloaded Trail</a>
covers all the more specific possibilities to store data.
</li>
</ul>
</section>
</div>
<!-- FOOTER -->
<div id="footer_wrap" class="outer">
<footer class="inner">
<p>
Maintained by
<a href="https://www.exedio.com/" target="_top">exedio</a>
Gesellschaft für Softwareentwicklung mbH.
</p>
<a href="https://validator.w3.org/check?uri=referer" class="validhtml">Valid HTML5</a>
<p>
Slate theme by <a href="https://github.com/jasoncostello">Jason Costello</a>.
Published with <a href="https://pages.github.com">GitHub Pages</a>.
</p>
</footer>
</div>
</body>
</html>