diff --git a/jOOQ-website/js/prettify/lang-sql.js b/jOOQ-website/js/prettify/lang-sql.js index f91fde9c2c..246ebcb169 100644 --- a/jOOQ-website/js/prettify/lang-sql.js +++ b/jOOQ-website/js/prettify/lang-sql.js @@ -44,7 +44,7 @@ PR['registerLangHandler']( // A comment is either a line comment that starts with two dashes, or // two dashes preceding a long bracketed block. [PR['PR_COMMENT'], /^(?:--[^\r\n]*|\/\*[\s\S]*?(?:\*\/|$))/], - [PR['PR_KEYWORD'], /^(?:ADD|AGGREGATE|ALL|ALTER|AND|ANY|AS|ASC|AT|AUTHORIZATION|BACKUP|BEGIN|BETWEEN|BREAK|BROWSE|BULK|BY|CASCADE|CASE|CHECK|CHECKPOINT|CLOSE|CLUSTERED|COALESCE|COLLATE|COLUMN|COMMIT|COMPUTE|CONNECT|CONSTRAINT|CONTAINS|CONTAINSTABLE|CONTINUE|CONVERT|CREATE|CROSS|CURRENT|CURRENT_DATE|CURRENT_TIME|CURRENT_TIMESTAMP|CURRENT_USER|CURSOR|DATABASE|DBCC|DEALLOCATE|DECLARE|DEFAULT|DELETE|DENY|DESC|DISK|DISTINCT|DISTRIBUTED|DOUBLE|DROP|DUMMY|DUMP|ELSE|ELSIF|END|ERRLVL|ESCAPE|EXCEPT|EXEC|EXECUTE|EXISTS|EXIT|FETCH|FILE|FILLFACTOR|FIRST|FOR|FOREIGN|FREETEXT|FREETEXTTABLE|FROM|FULL|FUNCTION|GOTO|GRANT|GROUP|HAVING|HOLDLOCK|IDENTITY|IDENTITYCOL|IDENTITY_INSERT|IF|IN|INDEX|INNER|INSERT|INTERSECT|INTO|IS|JOIN|KEY|KILL|LEFT|LIKE|LIMIT|LINENO|LOAD|MATCH|MATCHED|MEMBER|MERGE|NATIONAL|NATURAL|NEXT|NOCHECK|NOCYCLE|NONCLUSTERED|NOT|NULL|NULLIF|NULLS|OBJECT|OF|OFF|OFFSET|OFFSETS|ON|ONLY|OPEN|OPENDATASOURCE|OPENQUERY|OPENROWSET|OPENXML|OPTION|OR|ORDER|OUT|OUTER|OVER|PARALLEL|PARALLEL_ENABLE|PARTITION|PERCENT|PLAN|PIVOT|PRECEDING|PRECISION|PRIMARY|PRINT|PROC|PROCEDURE|PUBLIC|RAISERROR|READ|READTEXT|RECONFIGURE|REFERENCES|REPLICATION|RESTORE|RESTRICT|RETURN|REVOKE|RIGHT|ROLLBACK|ROW|ROWCOUNT|ROWGUIDCOL|ROWS|RULE|SAVE|SCHEMA|SELECT|SEQUENCE|SESSION_USER|SET|SETUSER|SHUTDOWN|SOME|START|STATIC|STATISTICS|SYMMETRIC|SYSTEM_USER|TABLE|TEXTSIZE|THEN|TO|TOP|TRAN|TRANSACTION|TRIGGER|TRUNCATE|TSEQUAL|TYPE|UNBOUNDED|UNION|UNIQUE|UNPIVOT|UPDATE|UPDATETEXT|USE|USER|USING|VALUES|VARYING|VIEW|WAITFOR|WHEN|WHERE|WHILE|WITH|WITHIN|WRITETEXT)(?=[^\w-]|$)/i, null], + [PR['PR_KEYWORD'], /^(?:ADD|AGGREGATE|ALL|ALTER|AND|ANY|AS|ASC|AT|AUTHORIZATION|BACKUP|BEGIN|BETWEEN|BREAK|BROWSE|BULK|BY|CASCADE|CASE|CHECK|CHECKPOINT|CLOSE|CLUSTERED|COALESCE|COLLATE|COLUMN|COMMIT|COMPUTE|CONNECT|CONSTRAINT|CONTAINS|CONTAINSTABLE|CONTINUE|CONVERT|CREATE|CROSS|CURRENT|CURRENT_DATE|CURRENT_TIME|CURRENT_TIMESTAMP|CURRENT_USER|CURSOR|DATABASE|DBCC|DEALLOCATE|DECLARE|DEFAULT|DELETE|DENY|DESC|DISK|DISTINCT|DISTRIBUTED|DOUBLE|DROP|DUMMY|DUMP|ELSE|ELSIF|END|ERRLVL|ESCAPE|EXCEPT|EXEC|EXECUTE|EXISTS|EXIT|FETCH|FILE|FILLFACTOR|FIRST|FOR|FOREIGN|FREETEXT|FREETEXTTABLE|FROM|FULL|FUNCTION|GOTO|GRANT|GROUP|HAVING|HOLDLOCK|IDENTITY|IDENTITYCOL|IDENTITY_INSERT|IF|IN|INDEX|INNER|INSERT|INTERSECT|INTO|IS|JOIN|KEY|KILL|LEFT|LIKE|LIMIT|LINENO|LOAD|MATCH|MATCHED|MEMBER|MERGE|NATIONAL|NATURAL|NEXT|NOCHECK|NOCYCLE|NONCLUSTERED|NOT|NULL|NULLIF|NULLS|OBJECT|OF|OFF|OFFSET|OFFSETS|ON|ONLY|OPEN|OPENDATASOURCE|OPENQUERY|OPENROWSET|OPENXML|OPTION|OR|ORDER|OUT|OUTER|OVER|PARALLEL|PARALLEL_ENABLE|PARTITION|PERCENT|PLAN|PIVOT|PRECEDING|PRECISION|PRIMARY|PRINT|PROC|PROCEDURE|PUBLIC|RAISERROR|READ|READTEXT|RECONFIGURE|REFERENCES|REPLACE|REPLICATION|RESTORE|RESTRICT|RETURN|REVOKE|RIGHT|ROLLBACK|ROW|ROWCOUNT|ROWGUIDCOL|ROWS|RULE|SAVE|SCHEMA|SELECT|SEQUENCE|SESSION_USER|SET|SETUSER|SHUTDOWN|SOME|START|STATIC|STATISTICS|SYMMETRIC|SYSTEM_USER|TABLE|TEXTSIZE|THEN|TO|TOP|TRAN|TRANSACTION|TRIGGER|TRUNCATE|TSEQUAL|TYPE|UNBOUNDED|UNION|UNIQUE|UNPIVOT|UPDATE|UPDATETEXT|USE|USER|USING|VALUES|VARYING|VIEW|WAITFOR|WHEN|WHERE|WHILE|WITH|WITHIN|WRITETEXT)(?=[^\w-]|$)/i, null], // A number is a hex integer literal, a decimal real literal, or in // scientific notation. [PR['PR_LITERAL'], diff --git a/jOOQ-website/src/main/resources/manual-2.5.xml b/jOOQ-website/src/main/resources/manual-2.5.xml index fdd642f42e..bcdd663513 100644 --- a/jOOQ-website/src/main/resources/manual-2.5.xml +++ b/jOOQ-website/src/main/resources/manual-2.5.xml @@ -1934,7 +1934,7 @@ create.select().from(BOOK).where(BOOK.ID.equal(3)).forUpdate().skipLocked();]]><

FOR UPDATE in CUBRID and SQL Server

- The SQL standard specifies a FOR UPDATE clause to be applicable for cursors. Most databases interpret this as being applicable for all SELECT statements. An exception to this rule are the CUBRID and SQL Server databases, that do not allow for any FOR UPDATE clause in a regular SQL SELECT statement. jOOQ simulates the FOR UPDATE behaviour, by locking record by record with JDBC. JDBC allows for specifying the flags TYPE_SCROLL_SENSITIVE, CONCUR_UPDATABLE for any statement, and then using ResultSet.updateXXX() methods to produce a cell-lock / row-lock. Here’s a simplified example in JDBC: + The SQL standard specifies a FOR UPDATE clause to be applicable for cursors. Most databases interpret this as being applicable for all SELECT statements. An exception to this rule are the CUBRID and SQL Server databases, that do not allow for any FOR UPDATE clause in a regular SQL SELECT statement. jOOQ simulates the FOR UPDATE behaviour, by locking record by record with JDBC. JDBC allows for specifying the flags TYPE_SCROLL_SENSITIVE, CONCUR_UPDATABLE for any statement, and then using ResultSet.updateXXX() methods to produce a cell-lock / row-lock. Here's a simplified example in JDBC:

Sequence execution - + +

Fetch values from a database sequence or serial

+

+ Most databases support sequences of some sort, to provide you with unique values to be used for primary keys and other enumerations. If you're using jOOQ's , it will generate a sequence object per sequence for you. There are two ways of using such a sequence object: +

+ +

Standalone calls to sequences

+

+ Instead of actually phrasing a select statement, you can also use the convenience methods: +

+ + + +

Inlining sequence references in SQL

+

+ You can inline sequence references in jOOQ SQL statements. The following are examples of how to do that: +

+ + + +

+ For more info about inlining sequence references in SQL statements, please refer to the manual's section about . +

+
Stored procedures and functions - + +

Procedures vs. functions

+

+ Many RDBMS support the concept of "routines", usually calling them procedures and/or functions. These concepts have been around in programming languages for a while, also outside of databases. Famous languages distinguishing procedures from functions are: +

+
    +
  • Ada
  • +
  • BASIC
  • +
  • Pascal
  • +
  • etc...
  • +
+

+ The general distinction between (stored) procedures and (stored) functions can be summarised like this: +

+ +

Procedures

+
    +
  • Are called using JDBC CallableStatement
  • +
  • Have no return value
  • +
  • Usually support OUT parameters
  • +
+ +

Functions

+
    +
  • Can be used in SQL statements
  • +
  • Have a return value
  • +
  • Usually don't support OUT parameters
  • +
+ +

Exceptions to these rules

+
    +
  • DB2, H2, and HSQLDB don't allow for JDBC escape syntax when calling functions. Functions must be used in a SELECT statement
  • +
  • H2 only knows functions (without OUT parameters)
  • +
  • Oracle functions may have OUT parameters
  • +
  • Oracle knows functions that must not be used in SQL statements for transactional reasons
  • +
  • Postgres only knows functions (with all features combined). OUT parameters can also be interpreted as return values, which is quite elegant/surprising, depending on your taste
  • +
  • The Sybase jconn3 JDBC driver doesn't handle null values correctly when using the JDBC escape syntax on functions
  • +
+

+ In general, it can be said that the field of routines (procedures / functions) is far from being standardised in modern RDBMS even if the SQL:2008 standard specifies things quite well. Every database has its ways and JDBC only provides little abstraction over the great variety of procedures / functions implementations, especially when advanced data types such as cursors / UDT's / arrays are involved. +

+

+ To simplify things a little bit, jOOQ handles both procedures and functions the same way, using a more general type. +

+ +

Using jOOQ for standalone calls to stored procedures and functions

+

+ If you're using jOOQ's , it will generate objects for you. Let's consider the following example: +

+ + + +

+ The generated artefacts can then be used as follows: +

+ + + +

+ But you can also call the procedure using a generated convenience method in a global Routines class: +

+ + + +

+ For more details about for procedures, see the manual's section about . +

+ +

Inlining stored function references in SQL

+

+ Unlike procedures, functions can be inlined in SQL statements to generate or , if you're using . Assume you have a function like this: +

+ + + +

+ The generated artefacts can then be used as follows: +

+ + + + + + +

+ For more info about inlining stored function references in SQL statements, please refer to the manual's section about . +

+
Oracle Packages - + +

Packages in Oracle

+

+ Oracle uses the concept of a PACKAGE to group several procedures/functions into a sort of namespace. The SQL 92 standard talks about "modules", to represent this concept, even if this is rarely implemented as such. This is reflected in jOOQ by the use of Java sub-packages in the destination package. Every Oracle package will be reflected by +

+
    +
  • A Java package holding classes for formal Java representations of the procedure/function in that package
  • +
  • A Java class holding convenience methods to facilitate calling those procedures/functions
  • +
+

+ Apart from this, the generated source code looks exactly like the one for standalone procedures/functions. +

+

+ For more details about for procedures and packages see the manual's section about . +

+
Oracle user-defined types and member procedures - + +

Member functions and procedures in Oracle

+

+ Oracle UDTs can have object-oriented structures including member functions and procedures. With Oracle, you can do things like this: +

+ + + +

+ These member functions and procedures can simply be mapped to Java methods: +

+ + + +

+ For more details about for UDTs see the manual's section about . +

+