You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

sql.html 12 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351
  1. <html>
  2. <head>
  3. <meta http-equiv="Content-Language" content="en-us">
  4. <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
  5. <title>SQL Task</title>
  6. </head>
  7. <body>
  8. <h2><a name="sql">Sql</a></h2>
  9. <h3>Description</h3>
  10. <p>Executes a series of SQL statements via JDBC to a database. Statements can
  11. either be read in from a text file using the <i>src</i> attribute or from
  12. between the enclosing SQL tags.</p>
  13. <p>Multiple statements can be provided, separated by semicolons (or the
  14. defined <i>delimiter</i>). Individual lines within the statements can be
  15. commented using either --, // or REM at the start of the line.</p>
  16. <p>The <i>autocommit</i> attribute specifies whether auto-commit should be
  17. turned on or off whilst executing the statements. If auto-commit is turned
  18. on each statement will be executed and committed. If it is turned off the
  19. statements will all be executed as one transaction.</p>
  20. <p>The <i>onerror</i> attribute specifies how to proceed when an error occurs
  21. during the execution of one of the statements.
  22. The possible values are: <b>continue</b> execution, only show the error;
  23. <b>stop</b> execution and commit transaction;
  24. and <b>abort</b> execution and transaction and fail task.</p>
  25. <h3>Parameters</h3>
  26. <table border="1" cellpadding="2" cellspacing="0">
  27. <tr>
  28. <td width="12%" valign="top"><b>Attribute</b></td>
  29. <td width="78%" valign="top"><b>Description</b></td>
  30. <td width="10%" valign="top"><b>Required</b></td>
  31. </tr>
  32. <tr>
  33. <td width="12%" valign="top">driver</td>
  34. <td width="78%" valign="top">Class name of the jdbc driver</td>
  35. <td width="10%" valign="top">Yes</td>
  36. </tr>
  37. <tr>
  38. <td width="12%" valign="top">url</td>
  39. <td width="78%" valign="top">Database connection url</td>
  40. <td width="10%" valign="top">Yes</td>
  41. </tr>
  42. <tr>
  43. <td width="12%" valign="top">userid</td>
  44. <td width="78%" valign="top">Database user name</td>
  45. <td width="10%" valign="top">Yes</td>
  46. </tr>
  47. <tr>
  48. <td width="12%" valign="top">password</td>
  49. <td width="78%" valign="top">Database password</td>
  50. <td width="10%" valign="top">Yes</td>
  51. </tr>
  52. <tr>
  53. <td width="12%" valign="top">src</td>
  54. <td width="78%" valign="top">File containing SQL statements</td>
  55. <td width="10%" valign="top">Yes, unless statements enclosed within tags</td>
  56. </tr>
  57. <tr>
  58. <td valign="top">encoding</td>
  59. <td valign="top">The encoding of the files containing SQL statements</td>
  60. <td align="center">No - defaults to default JVM encoding</td>
  61. </tr>
  62. <tr>
  63. <td width="12%" valign="top">delimiter</td>
  64. <td width="78%" valign="top">String that separates SQL statements</td>
  65. <td width="10%" valign="top">No, default &quot;;&quot;</td>
  66. </tr>
  67. <tr>
  68. <td width="12%" valign="top">autocommit</td>
  69. <td width="78%" valign="top">Auto commit flag for database connection (default false)</td>
  70. <td width="10%" valign="top">No, default &quot;false&quot;</td>
  71. </tr>
  72. <tr>
  73. <td width="12%" valign="top">print</td>
  74. <td width="78%" valign="top">Print result sets from the statements (default false)</td>
  75. <td width="10%" valign="top">No, default &quot;false&quot;</td>
  76. </tr>
  77. <tr>
  78. <td width="12%" valign="top">showheaders</td>
  79. <td width="78%" valign="top">Print headers for result sets from the statements (default true)</td>
  80. <td width="10%" valign="top">No, default &quot;true&quot;</td>
  81. </tr>
  82. <tr>
  83. <td width="12%" valign="top">output</td>
  84. <td width="78%" valign="top">Output file for result sets (defaults to System.out)</td>
  85. <td width="10%" valign="top">No (print to System.out by default)</td>
  86. </tr>
  87. <tr>
  88. <td valign="top">append</td>
  89. <td valign="top">whether output should be appended to or overwrite
  90. an existing file. Defaults to false.</td>
  91. <td align="center" valign="top">No</td>
  92. </tr>
  93. <tr>
  94. <td width="12%" valign="top">classpath</td>
  95. <td width="78%" valign="top">Classpath used to load driver</td>
  96. <td width="10%" valign="top">No (use system classpath)</td>
  97. </tr>
  98. <tr>
  99. <td width="12%" valign="top">classpathref</td>
  100. <td width="78%" valign="top">The classpath to use, given as a <a href="../using.html#references">reference</a> to a path defined elsewhere.</td>
  101. <td width="10%" valign="top">No (use system classpath)</td>
  102. </tr>
  103. <tr>
  104. <td width="12%" valign="top">onerror</td>
  105. <td width="78%" valign="top">Action to perform when statement fails: continue, stop, abort</td>
  106. <td width="10%" valign="top">No, default &quot;abort&quot;</td>
  107. </tr>
  108. <tr>
  109. <td width="12%" valign="top">rdbms</td>
  110. <td width="78%" valign="top">Execute task only if this rdbms</td>
  111. <td width="10%" valign="top">No (no restriction)</td>
  112. </tr>
  113. <tr>
  114. <td width="12%" valign="top">version</td>
  115. <td width="78%" valign="top">Execute task only if rdbms version match</td>
  116. <td width="10%" valign="top">No (no restriction)</td>
  117. </tr>
  118. <tr>
  119. <td width="12%" valign="top">caching</td>
  120. <td width="78%" valign="top">Should the task cache loaders and the driver?</td>
  121. <td width="10%" valign="top">No (default=true)</td>
  122. </tr>
  123. <tr>
  124. <td width="12%" valign="top">delimitertype</td>
  125. <td width="78%" valign="top">Control whether the delimiter will only be recognized on a line by itself.<br>
  126. Can be "normal" -anywhere on the line, or "row", meaning it must be on a line by itself</td>
  127. <td width="10%" valign="top">No (default:normal)</td>
  128. </tr>
  129. <tr>
  130. <td width="12%" valign="top">keepformat</td>
  131. <td width="78%" valign="top">Control whether the format of the sql will be preserved.<br>
  132. Usefull when loading packages and procedures.
  133. <td width="10%" valign="top">No (default=false)</td>
  134. </tr>
  135. <tr>
  136. <td width="12%" valign="top">escapeprocessing</td>
  137. <td width="78%" valign="top">Control whether the Java statement
  138. object will perform escape substitution.<br>
  139. See <a
  140. href="http://java.sun.com/j2se/1.4.2/docs/api/java/sql/Statement.html#setEscapeProcessing(boolean)">Statement's
  141. API docs</a> for details. <em>Since Ant 1.6</em>.
  142. <td width="10%" valign="top">No (default=true)</td>
  143. </tr>
  144. <tr>
  145. <td width="12%" valign="top">expandproperties</td>
  146. <td width="78%" valign="top">Set to true to turn on property expansion in
  147. nested SQL, inline in the task or nested transactions. <em>Since Ant 1.7</em>.
  148. <td width="10%" valign="top">No (default=false)</td>
  149. </tr>
  150. </table>
  151. <h3>Parameters specified as nested elements</h3>
  152. <h4>transaction</h4>
  153. <p>Use nested <code>&lt;transaction&gt;</code>
  154. elements to specify multiple blocks of commands to the executed
  155. executed in the same connection but different transactions. This
  156. is particularly useful when there are multiple files to execute
  157. on the same schema.</p>
  158. <table border="1" cellpadding="2" cellspacing="0">
  159. <tr>
  160. <td valign="top"><b>Attribute</b></td>
  161. <td valign="top"><b>Description</b></td>
  162. <td align="center" valign="top"><b>Required</b></td>
  163. </tr>
  164. <tr>
  165. <td valign="top">src</td>
  166. <td valign="top">File containing SQL statements</td>
  167. <td valign="top" align="center">Yes, unless statements enclosed within tags</td>
  168. </tr>
  169. </table>
  170. <p>The <code>&lt;transaction&gt;</code> element supports any <a
  171. href="../CoreTypes/resources.html">resource</a> or single element
  172. resource collection as nested element to specify the resource
  173. containing the SQL statements.</p>
  174. <h4>any <a href="../CoreTypes/resources.html">resource</a> or resource
  175. collection</h4>
  176. <p>You can specify multiple sources via nested resource collection
  177. elements. Each resource of the collection will be run in a
  178. transaction of its own. Prior to Ant 1.7 only filesets were
  179. supported. Use a sort resource collection to get a predictable order
  180. of transactions. </p>
  181. <h4>classpath</h4>
  182. <p><code>Sql</code>'s <em>classpath</em> attribute is a <a
  183. href="../using.html#path">PATH like structure</a> and can also be set via a nested
  184. <em>classpath</em> element. It is used to load the JDBC classes.</p>
  185. <h3>Examples</h3>
  186. <blockquote><pre>&lt;sql
  187. driver=&quot;org.database.jdbcDriver&quot;
  188. url=&quot;jdbc:database-url&quot;
  189. userid=&quot;sa&quot;
  190. password=&quot;pass&quot;
  191. src=&quot;data.sql&quot;
  192. /&gt;
  193. </pre></blockquote>
  194. <p>Connects to the database given in <i>url</i> as the sa user using the
  195. org.database.jdbcDriver and executes the SQL statements contained within
  196. the file data.sql</p>
  197. <blockquote><pre>&lt;sql
  198. driver=&quot;org.database.jdbcDriver&quot;
  199. url=&quot;jdbc:database-url&quot;
  200. userid=&quot;sa&quot;
  201. password=&quot;pass&quot;
  202. &gt;
  203. insert
  204. into table some_table
  205. values(1,2,3,4);
  206. truncate table some_other_table;
  207. &lt;/sql&gt;
  208. </pre></blockquote>
  209. <p>Connects to the database given in <i>url</i> as the sa
  210. user using the org.database.jdbcDriver and executes the two SQL statements
  211. inserting data into some_table and truncating some_other_table. Ant Properties
  212. in the nested text will not be expanded.</p>
  213. <p>Note that you may want to enclose your statements in
  214. <code>&lt;![CDATA[</code> ... <code>]]&gt;</code> sections so you don't
  215. need to escape <code>&lt;</code>, <code>&gt;</code> <code>&amp;</code>
  216. or other special characters. For example:</p>
  217. <blockquote><pre>&lt;sql
  218. driver=&quot;org.database.jdbcDriver&quot;
  219. url=&quot;jdbc:database-url&quot;
  220. userid=&quot;sa&quot;
  221. password=&quot;pass&quot;
  222. &gt;&lt;![CDATA[
  223. update some_table set column1 = column1 + 1 where column2 &lt; 42;
  224. ]]&gt;&lt;/sql&gt;
  225. </pre></blockquote>
  226. The following command turns property expansion in nested text on (it is off purely for backwards
  227. compatibility), then creates a new user in the HSQLDB database using Ant properties.
  228. <blockquote><pre>&lt;sql
  229. driver="org.hsqldb.jdbcDriver";
  230. url="jdbc:hsqldb:file:${database.dir}"
  231. userid="sa"
  232. password=""
  233. expandProperties="true"
  234. &gt;
  235. &lt;transaction&gt;
  236. CREATE USER ${newuser} PASSWORD ${newpassword}
  237. &lt;/transaction&gt;
  238. &lt;/sql&gt;
  239. </pre></blockquote>
  240. <p>The following connects to the database given in url as the sa user using
  241. the org.database.jdbcDriver and executes the SQL statements contained within
  242. the files data1.sql, data2.sql and data3.sql and then executes the truncate
  243. operation on <i>some_other_table</i>.</p>
  244. <blockquote><pre>&lt;sql
  245. driver=&quot;org.database.jdbcDriver&quot;
  246. url=&quot;jdbc:database-url&quot;
  247. userid=&quot;sa&quot;
  248. password=&quot;pass&quot; &gt;
  249. &lt;transaction src=&quot;data1.sql&quot;/&gt;
  250. &lt;transaction src=&quot;data2.sql&quot;/&gt;
  251. &lt;transaction src=&quot;data3.sql&quot;/&gt;
  252. &lt;transaction&gt;
  253. truncate table some_other_table;
  254. &lt;/transaction&gt;
  255. &lt;/sql&gt;
  256. </pre></blockquote>
  257. <p>The following example does the same as (and may execute additional
  258. SQL files if there are more files matching the pattern
  259. <code>data*.sql</code>) but doesn't guarantee that data1.sql will be
  260. run before <code>data2.sql</code>.</p>
  261. <blockquote><pre>&lt;sql
  262. driver=&quot;org.database.jdbcDriver&quot;
  263. url=&quot;jdbc:database-url&quot;
  264. userid=&quot;sa&quot;
  265. password=&quot;pass&quot;&gt;
  266. &lt;path&gt;
  267. &lt;fileset dir=&quot;.&quot;&gt;
  268. &lt;include name=&quot;data*.sql&quot;/&gt;
  269. &lt;/fileset&gt;
  270. &lt;path&gt;
  271. &lt;transaction&gt;
  272. truncate table some_other_table;
  273. &lt;/transaction&gt;
  274. &lt;/sql&gt;
  275. </pre></blockquote>
  276. <p>The following connects to the database given in url as the sa user using the
  277. org.database.jdbcDriver and executes the SQL statements contained within the
  278. file data.sql, with output piped to outputfile.txt, searching /some/jdbc.jar
  279. as well as the system classpath for the driver class.</p>
  280. <blockquote><pre>&lt;sql
  281. driver=&quot;org.database.jdbcDriver&quot;
  282. url=&quot;jdbc:database-url&quot;
  283. userid=&quot;sa&quot;
  284. password=&quot;pass&quot;
  285. src=&quot;data.sql&quot;
  286. print=&quot;yes&quot;
  287. output=&quot;outputfile.txt&quot;
  288. &gt;
  289. &lt;classpath&gt;
  290. &lt;pathelement location=&quot;/some/jdbc.jar&quot;/&gt;
  291. &lt;/classpath&gt;
  292. &lt;/sql&gt;
  293. </pre></blockquote>
  294. <p>The following will only execute if the RDBMS is &quot;oracle&quot; and the version
  295. starts with &quot;8.1.&quot;</p>
  296. <blockquote><pre>&lt;sql
  297. driver=&quot;org.database.jdbcDriver&quot;
  298. url=&quot;jdbc:database-url&quot;
  299. userid=&quot;sa&quot;
  300. password=&quot;pass&quot;
  301. src=&quot;data.sql&quot;
  302. rdbms=&quot;oracle&quot;
  303. version=&quot;8.1.&quot;
  304. &gt;
  305. insert
  306. into table some_table
  307. values(1,2,3,4);
  308. truncate table some_other_table;
  309. &lt;/sql&gt;
  310. </pre></blockquote>
  311. <hr>
  312. <p align="center">Copyright &copy; 2000-2006 The Apache Software Foundation. All rights
  313. Reserved.</p>
  314. </body>
  315. </html>