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 [EMAIL PROTECTED] 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()); } } }