You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by bo...@apache.org on 2008/05/29 17:50:47 UTC
svn commit: r661370 - in /ant/sandbox/antlibs/dbpatch: TODO docs/cover.html
docs/dbpatch.html src/main/org/apache/ant/dbpatch/AntDBPatchRunner.java
src/main/org/apache/ant/dbpatch/DBPatchTask.java
Author: bodewig
Date: Thu May 29 08:50:47 2008
New Revision: 661370
URL: http://svn.apache.org/viewvc?rev=661370&view=rev
Log:
Add some documentation, override unsupported attributes of base task. PR 44969. Submitted by Andrus Adamchik
Modified:
ant/sandbox/antlibs/dbpatch/TODO
ant/sandbox/antlibs/dbpatch/docs/cover.html
ant/sandbox/antlibs/dbpatch/docs/dbpatch.html
ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/AntDBPatchRunner.java
ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/DBPatchTask.java
Modified: ant/sandbox/antlibs/dbpatch/TODO
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/dbpatch/TODO?rev=661370&r1=661369&r2=661370&view=diff
==============================================================================
--- ant/sandbox/antlibs/dbpatch/TODO (original)
+++ ant/sandbox/antlibs/dbpatch/TODO Thu May 29 08:50:47 2008
@@ -2,8 +2,6 @@
What we need for release 1.0:
* Unit tests
-* Documentation
-* Support for passing driver classpath ref
* Support for alternative workflow that requires no index file,
and uses numbered patch files instead
(such workflow targets smaller projects with less commit concurrency).
Modified: ant/sandbox/antlibs/dbpatch/docs/cover.html
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/dbpatch/docs/cover.html?rev=661370&r1=661369&r2=661370&view=diff
==============================================================================
--- ant/sandbox/antlibs/dbpatch/docs/cover.html (original)
+++ ant/sandbox/antlibs/dbpatch/docs/cover.html Thu May 29 08:50:47 2008
@@ -1,4 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
<html>
<head>
<meta content="en-us" http-equiv="Content-Language" />
@@ -6,7 +22,58 @@
<title>DBPatch</title>
</head>
<body>
- <h2>DBPatch</h2>
- <p>DBPatch library is intended to maintain versioning of a database schema and data during iterative development.</p>
+ <h2>DBPatch Antlib</h2>
+
+ <h3>Overview</h3>
+ <p>DBPatch is an Antlib for maintaining evolving database schema and data. It provides the approach
+ and the tools to bring up multiple databases in sync with the state of the database and application code
+ development. It is used in development allowing multiple programmers to synchronize their local databases
+ with the current state of the application code in repository and in deployment to synchronize production
+ or test database with the version of the deployed code.</p>
+
+ <p>To include DBPatch Antlib in your build, use the following code:</p>
+
+ <pre><typedef resource="org/apache/ant/dbpatch/antlib.xml"/></pre>
+
+ <h3>How It Works</h3>
+ <p>From the DBPatch perspective there are two types of changes that are made to the database:
+ (1) those made by the applications during their normal operation course and (2) those made by the programmers
+ during the development and deployed periodically as a part of the release process. DBPatch makes the assumption
+ that within a finite development cycle only the second category of changes (those made by developers) are
+ needed to describe each distinct database state. The difference between each subsequent state is represented
+ as a <i>patch</i>. A patch is simply a file that contains a SQL script that performs some operation (e.g.
+ ALTER TABLE, INSERT, etc.). Patch files are created by programmers in the course of development and checked
+ in the repository together with the application code. DBPatch tools keep track of the database state and ensure
+ that each patch is only applied once and all patches are applied in the correct predefined order.</p>
+ <p>
+
+ <h3>DBPatch Files</h3>
+ <h4>Using Explicit Index File</h4>
+ <p>With the index file approach, there is a single index file that lists all the patch files in the order they
+ should be applied. Index file contains one patch name per line. Empty lines and lines that
+ start with "//" or "#" (comments) are ignored. Index file and patch files can have any names. There are no
+ restrictions on naming them. Patch file names are resolved relative to the directory where the index file is
+ located.</p>
+ <p>Here is an example index file:</p>
+
+ <pre># This is a comment
+somepatch.sql
+someotherpatch.sql
+
+// another comment
+lastpatch.sql</pre>
+
+<p>Here is an example patch file:</p>
+<pre>ALTER TABLE mytable ADD COLUMN newcolumn VARCHAR(20) NOT NULL;
+INSERT INTO mytable (id, oldcolumn, newcolumn) VALUES (1, 'X', 'Y');
+</pre>
+
+ <h4>Using Implicit Ordering</h4>
+ <p><i>TODO: this mode is not supported yet</i></p>
+
+ <h3>Tasks</h3>
+ <ul>
+ <li><a href="dbpatch.html">DBPatch</a> - a task that brings up a target database in sync with the latest patch state.</li>
+ </p>
</body>
</html>
Modified: ant/sandbox/antlibs/dbpatch/docs/dbpatch.html
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/dbpatch/docs/dbpatch.html?rev=661370&r1=661369&r2=661370&view=diff
==============================================================================
--- ant/sandbox/antlibs/dbpatch/docs/dbpatch.html (original)
+++ ant/sandbox/antlibs/dbpatch/docs/dbpatch.html Thu May 29 08:50:47 2008
@@ -19,60 +19,147 @@
<head>
<meta content="en-us" http-equiv="Content-Language" />
<link href="style.css" rel="stylesheet" type="text/css" />
- <title>DBPathc</title>
+ <title>DBPatch</title>
</head>
<body>
<h2>DBPatch</h2>
- <p>TODO: something about this antlib</p>
- <pre>
- An Ant task that supports maintaining evolving database schema via incremental
-SQL "patches". A "DB Patch" is a text file that contains native SQL code for
-the target database. Patches are indexed in a special "patch index" file that defines
-the order of patches. Patch names can be arbitrary. An extra arbitrary "patchReleaseId"
-attribute is defined to provide a simple namespace for patches. Otherwise the task is
-configured similar to the standard Ant "SQL" task:
-
- http://ant.apache.org/manual/CoreTasks/sql.html
-
-The following taskdef is needed:
-
- <taskdef name="dbpatch" classname="org.apache.cayenne.tools.DBPatchTask"/>
-
-
-An example of dbpatch task invocation:
-
- <dbpatch
- patchIndex="patches/index.txt"
- patchReleaseId="${version}"
- driver="com.mysql.jdbc.Driver"
- url="${db.url}"
- userid="${db.userid}"
- password="${db.password}"/>
-
-DB patch task does all its initial setup tasks on its own. Namely, on first run it creates
-a table called "patch_tracking" (or a table with a different name if a user sets a 'patch_tracking'
-attribute). This table stores the names of patches that have been applied to the target DB, so
-that subsequent runs could skip them.
-
-Supported attributes:
-
-patchIndex:
- (Required)
- A text file that contains the names of the patches to run in the order they should be executed,
+ <h3>Description</h3>
+ <p>DBPatch is an Ant task that brings the state of the target database in sync with
+ the local patches. It is usually run locally as a part of the build process to update a local development
+ database or it can be run before deployment to update a test or production database. Read more
+ about patch creation strategies and including the Antlib <a href="cover.html">here</a>.
+ </p>
+
+ <p>DBPatch uses a special database table to track which patches were already applied. Such table is
+ created automatically if it is missing, so it requires no preliminary setup. However if the database
+ user id used to run DB patches does not have enough permissions to create tables in the target table space,
+ a user must take care of setting it up. The default table structure is the following (table and column names
+ can be customized, see parameter definitions for details):</p>
+
+ <pre>CREATE TABLE patch_tracking(
+ ID INTEGER NOT NULL PRIMARY KEY,
+ PATCH_NAME VARCHAR(100),
+ PATCH_RELEASE_ID VARCHAR(20),
+ APPLIED_TIMESTAMP TIMESTAMP,
+ PATCH_UTILITY_VERSION VARCHAR(20)
+)</pre>
+
+ <h3>Parameters</h3>
+ <table border="1" cellpadding="2" cellspacing="0">
+ <tr>
+
+ <td valign="top"><b>Attribute</b></td>
+ <td valign="top"><b>Description</b></td>
+ <td align="center" valign="top"><b>Required</b></td>
+ </tr>
+ <tr>
+ <td valign="top">patchindex</td>
+ <td valign="top">A text file that contains the names of the patches to run in the order they should be executed,
one file per line. Empty lines and lines starting with # or // are skipped. The rest are treated
- as file names in the directory relative to the patch index file directory.
-patchTableName:
- (Optional, default value is 'patch_tracking')
- An attribute that defines the name of the table where patch tracking information is stored.
- Can contain schema name. E.g. "myschema.mypatchtable".
-patchReleaseId:
- (Optional, default is null)
- Defines a namespace for patch file names. All patch files must have unique names for a given patch
- release id.
-
-... SQL task attributes ...
-
+ as file names in the directory relative to the patch index file directory.</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">patchreleaseid</td>
+ <td valign="top">Defines a namespace for patch file names. All patch files must have unique names for a given patch
+ release id.</td>
+ <td valign="top" align="center">No - default is empty</td>
+ </tr>
+ <tr>
+ <td valign="top">patchtablename</td>
+ <td valign="top">An attribute that defines the name of the table where patch tracking information is stored.
+ Can contain schema name. E.g. "myschema.mypatchtable".</td>
+ <td valign="top" align="center">No - default is 'patch_tracking'</td>
+ </tr>
+ <tr>
+ <td valign="top">driver</td>
+ <td valign="top">Class name of the jdbc driver</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">url</td>
+ <td valign="top">Database connection url</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">userid</td>
+ <td valign="top">Database user name</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">password</td>
+ <td valign="top">Database password</td>
+ <td valign="top" align="center">Yes</td>
+ </tr>
+ <tr>
+ <td valign="top">encoding</td>
+ <td valign="top">Encoding of the SQL patch files</td>
+ <td valign="top" align="center">No - defaults to default JVM encoding</td>
+ </tr>
+ <tr>
+ <td valign="top">delimiter</td>
+ <td valign="top">String that separates SQL statements</td>
+ <td valign="top" align="center">No - default ";"</td>
+ </tr>
+ <tr>
+ <td valign="top">autocommit</td>
+ <td valign="top">Auto commit flag for database connection</td>
+ <td valign="top" align="center">No - default "false"</td>
+ </tr>
+ <tr>
+ <td valign="top">showheaders</td>
+ <td valign="top">Print headers for result sets from the statements</td>
+ <td valign="top">No, default "true"</td>
+ </tr>
+ <tr>
+ <td valign="top">showtrailers</td>
+ <td valign="top">Print trailer for number of rows affected</td>
+ <td valign="top">No, default "true"</td>
+ </tr>
+ <tr>
+ <td valign="top">classpath</td>
+ <td valign="top">Classpath used to load driver</td>
+ <td valign="top">No (use system classpath)</td>
+ </tr>
+ <tr>
+ <td valign="top">classpathref</td>
+ <td valign="top">The classpath to use, given as a reference to a path defined elsewhere.</td>
+ <td valign="top">No (use system classpath)</td>
+ </tr>
+ <tr>
+ <td valign="top">delimitertype</td>
+ <td valign="top">Control whether the delimiter will only be recognized on a line by itself.
+ Can be "normal" -anywhere on the line, or "row", meaning it must be on a line by itself</td>
+ <td valign="top">No (default:normal)</td>
+ </tr>
+ <tr>
+ <td valign="top">keepformat</td>
+ <td valign="top">Control whether the format of the sql will be preserved.
+ Useful when loading packages and procedures.
+ <td valign="top">No (default=false)</td>
+ </tr>
+ <tr>
+ <td>escapeprocessing</td>
+ <td valign="top">Control whether the Java statement
+ object will perform escape substitution.<br>
+ See <a
+ href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Statement.html#setEscapeProcessing(boolean)">Statement's
+ API docs</a> for details. <em>Since Ant 1.6</em>.
+ <td valign="top">No (default=true)</td>
+ </tr>
+</table>
- </pre>
+<h3>Examples</h3>
+
+<p>Running dbpatches listed in "patches/index.txt":</p>
+
+<pre><dbpatch
+ patchIndex="patches/index.txt"
+ patchReleaseId="${version}"
+ driver="com.mysql.jdbc.Driver"
+ url="${db.url}"
+ userid="${db.userid}"
+ password="${db.password}"
+ classpathref="my.drivers.ref"/>
</body>
</html>
Modified: ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/AntDBPatchRunner.java
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/AntDBPatchRunner.java?rev=661370&r1=661369&r2=661370&view=diff
==============================================================================
--- ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/AntDBPatchRunner.java (original)
+++ ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/AntDBPatchRunner.java Thu May 29 08:50:47 2008
@@ -54,7 +54,6 @@
logVerbose("Will run patch: " + patchName);
- parentTask.setSrc(patchFile);
- parentTask.runSQL();
+ parentTask.runPatch(patchFile);
}
}
Modified: ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/DBPatchTask.java
URL: http://svn.apache.org/viewvc/ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/DBPatchTask.java?rev=661370&r1=661369&r2=661370&view=diff
==============================================================================
--- ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/DBPatchTask.java (original)
+++ ant/sandbox/antlibs/dbpatch/src/main/org/apache/ant/dbpatch/DBPatchTask.java Thu May 29 08:50:47 2008
@@ -63,6 +63,96 @@
this.patchReleaseId = patchReleaseId;
}
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setSrc(File srcFile) {
+ throw new UnsupportedOperationException(
+ "'src' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setOutput(File output) {
+ throw new UnsupportedOperationException(
+ "'output' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setPrint(boolean print) {
+ throw new UnsupportedOperationException(
+ "'print' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setAppend(boolean append) {
+ throw new UnsupportedOperationException(
+ "'append' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setOnerror(OnError action) {
+ throw new UnsupportedOperationException(
+ "'onerror' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setRdbms(String rdbms) {
+ throw new UnsupportedOperationException(
+ "'rdbms' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setVersion(String version) {
+ throw new UnsupportedOperationException(
+ "'version' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setCaching(boolean enable) {
+ throw new UnsupportedOperationException(
+ "'caching' parameter is not supported");
+ }
+
+ /**
+ * Blocks super implementation by throwing an UnsupportedOperationException
+ * to prevent users from using it.
+ */
+ public void setExpandProperties(boolean expandProperties) {
+ throw new UnsupportedOperationException(
+ "'caching' parameter is not supported");
+ }
+
+ /**
+ * A callback method repeatedly invoked by {@link AntDBPatchRunner} to
+ * execute each patch.
+ */
+ void runPatch(File patchFile) {
+ super.setSrc(patchFile);
+ runSQL();
+ }
+
public void execute() throws BuildException {
validate();
initDefaults();
@@ -70,9 +160,7 @@
Connection connection = getConnection();
try {
DBPatchRunner runner = new AntDBPatchRunner(this, connection,
- patchIndex,
- patchTableName,
- patchReleaseId);
+ patchIndex, patchTableName, patchReleaseId);
runner.execute();
} catch (SQLException e) {
throw new BuildException("SQL exception " + e.getMessage(), e);
@@ -103,7 +191,7 @@
if (!patchIndex.isFile()) {
throw new BuildException("Invalid 'patchIndex' file specified: "
- + patchIndex.getAbsolutePath());
+ + patchIndex.getAbsolutePath());
}
}
}