ant-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject 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
Date Thu, 29 May 2008 15:50:47 GMT
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>&lt;typedef resource="org/apache/ant/dbpatch/antlib.xml"/&gt;</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 &quot;true&quot;</td>
+  </tr>
+  <tr>
+    <td valign="top">showtrailers</td>
+    <td valign="top">Print trailer for number of rows affected</td>
+    <td valign="top">No, default &quot;true&quot;</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>&lt;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"/&gt;
   </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());
         }
     }
 }



Mime
View raw message