Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
docs: move docs from www/documentation/head (#744)
* docs: move docs from www/documentation/head Move documentation from www/documentation/head/ to pgjdbc/docs/ This makes easy to update the documentation when a change is made to the driver. [skip ci] * update intro
- Loading branch information
Showing
with
4,460 additions
and 0 deletions.
- +1 −0 docs/.gitignore
- +77 −0 docs/8-date-time.md
- +3 −0 docs/_config.yml
- +90 −0 docs/_layouts/default_docs.html
- +179 −0 docs/binary-data.md
- +116 −0 docs/callproc.md
- +28 −0 docs/classpath.md
- +440 −0 docs/connect.md
- +44 −0 docs/datasource.md
- +24 −0 docs/ddl.md
- +93 −0 docs/ds-cpds.md
- +178 −0 docs/ds-ds.md
- +480 −0 docs/escaped-functions.md
- +23 −0 docs/escapes-datetime.md
- +57 −0 docs/escapes.md
- +37 −0 docs/ext.md
- +68 −0 docs/geometric.md
- +253 −0 docs/index.html
- +29 −0 docs/intro.md
- +68 −0 docs/jndi.md
- +20 −0 docs/largeobjects.md
- +148 −0 docs/listennotify.md
- +49 −0 docs/load.md
- +450 −0 docs/media/css/docs.css
- +98 −0 docs/media/css/global.css
- +101 −0 docs/media/css/table.css
- +162 −0 docs/media/css/text.css
- BIN docs/media/favicon.ico
- BIN docs/media/img/docs/bg_hdr.png
- BIN docs/media/img/layout/hdr_left3a.png
- BIN docs/media/img/layout/nav_tbl_btm.png
- BIN docs/media/img/layout/nav_tbl_top.png
- +17 −0 docs/outer-joins-escape.md
- +25 −0 docs/prepare.md
- +114 −0 docs/query.md
- +18 −0 docs/reading.md
- +374 −0 docs/replication.md
- +19 −0 docs/resultset.md
- +121 −0 docs/server-prepare.md
- +44 −0 docs/setup.md
- +70 −0 docs/ssl-client.md
- +29 −0 docs/ssl-factory.md
- +37 −0 docs/ssl.md
- +31 −0 docs/statement.md
- +38 −0 docs/thread.md
- +121 −0 docs/tomcat.md
- +32 −0 docs/update.md
- +34 −0 docs/use.md
- +20 −0 docs/your-database.md
@@ -0,0 +1 @@ | ||
_site |
@@ -0,0 +1,77 @@ | ||
--- | ||
layout: default_docs | ||
title: Using Java 8 Date and Time classes | ||
header: Chapter 5. Using Java 8 Date and Time classes | ||
resource: media | ||
previoustitle: Creating and Modifying Database Objects | ||
previous: ddl.html | ||
nexttitle: Chapter 6. Calling Stored Functions | ||
next: callproc.html | ||
--- | ||
|
||
The PostgreSQL™ JDBC driver implements native support for the | ||
[Java 8 Date and Time API](http://www.oracle.com/technetwork/articles/java/jf14-date-time-2125367.html) | ||
(JSR-310) using JDBC 4.2. | ||
|
||
<a name="8-date-time-supported-data-types"></a> | ||
**Table 5.1. Supported escaped numeric functions** | ||
|
||
<table summary="Supported data type" border="1"> | ||
<tr> | ||
<th>PostgreSQL™</th> | ||
<th>Java SE 8</th> | ||
</tr> | ||
<tbody> | ||
<tr> | ||
<td>DATE</td> | ||
<td>LocalDate</td> | ||
</tr> | ||
<tr> | ||
<td>TIME [ WITHOUT TIMEZONE ]</td> | ||
<td>LocalTime</td> | ||
</tr> | ||
<tr> | ||
<td>TIMESTAMP [ WITHOUT TIMEZONE ]</td> | ||
<td>LocalDateTime</td> | ||
</tr> | ||
<tr> | ||
<td>TIMESTAMP WITH TIMEZONE</td> | ||
<td>OffsetDateTime</td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
|
||
This is closely aligned with tables B-4 and B-5 of the JDBC 4.2 specification. | ||
Note that `ZonedDateTime`, `Instant` and | ||
`OffsetTime / TIME [ WITHOUT TIMEZONE ]` are not supported. Also note | ||
that all `OffsetDateTime` will instances will have be in UTC (have offset 0). | ||
This is because the backend stores them as UTC. | ||
|
||
<a name="reading-example"></a> | ||
**Example 5.5. Reading Java 8 Date and Time values using JDBC** | ||
|
||
`Statement st = conn.createStatement();` | ||
`ResultSet rs = st.executeQuery("SELECT * FROM mytable WHERE columnfoo = 500");` | ||
`while (rs.next())` | ||
`{` | ||
`System.out.print("Column 1 returned ");` | ||
`LocalDate localDate = rs.getObject(1, LocalDate.class));` | ||
`System.out.println(localDate);` | ||
`}` | ||
`rs.close();` | ||
`st.close();` | ||
|
||
For other data types simply pass other classes to `#getObject`. | ||
Note that the Java data types needs to match the SQL data types in table 7.1. | ||
|
||
|
||
<a name="writing-example"></a> | ||
**Example 5.5. Writing Java 8 Date and Time values using JDBC** | ||
|
||
`LocalDate localDate = LocalDate.now();` | ||
`PreparedStatement st = conn.prepareStatement("INSERT INTO mytable (columnfoo) VALUES (?)");` | ||
`st.setObject(1, localDate);` | ||
`st.executeUpdate();` | ||
`st.close();` | ||
|
||
|
@@ -0,0 +1,3 @@ | ||
name: PostgreSQL JDBC Driver HEAD documentation | ||
markdown: kramdown | ||
highlighter: rouge |
@@ -0,0 +1,90 @@ | ||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | ||
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" dir="ltr"> | ||
<head> | ||
<title>{{ page.title }}</title> | ||
<meta http-equiv="Content-Type" content="text/xhtml; charset=utf-8" /> | ||
<meta name="description" content="The official site for the PostgreSQL JDBC Driver" /> | ||
<meta name="copyright" content="The PostgreSQL Global Development Group" /> | ||
|
||
<style type="text/css" media="screen" title="Normal Text">@import url("{{ page.resource }}/css/docs.css");</style> | ||
|
||
<link rel="shortcut icon" href="media/favicon.ico" /> | ||
</head> | ||
|
||
<body> | ||
<div id="docHeader"> | ||
<div id="docHeaderLogo"> | ||
<a href="http://www.postgresql.org/" title="PostgreSQL"><img src="media/img/layout/hdr_left3a.png" alt="PostgreSQL" height="80" width="390" /></a> | ||
</div> | ||
</div> | ||
|
||
<div id="docContainerWrap"> | ||
<div id="docContainer"> | ||
<div id="docContent"> | ||
|
||
<div class="NAVHEADER"> | ||
<table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0"> | ||
<tbody> | ||
<tr> | ||
<th colspan="3" valign="bottom" align="center"> | ||
<h2 class="TITLE">{{ page.header }}</h2> | ||
</th> | ||
</tr> | ||
<tr> | ||
<td valign="top" width="20%" align="left"> | ||
<a title="{{ page.previoustitle }}" href="{{ page.previous }}" accesskey="P">Prev</a> | ||
</td> | ||
<td valign="bottom" width="60%" align="center"> </td> | ||
<td valign="top" width="20%" align="right"> | ||
<a title="{{ page.nexttitle }}" href="{{ page.next }}" accesskey="N">Next</a> | ||
</td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
<hr class="c1" width="100%" /> | ||
</div> <!-- NAVHEADER --> | ||
|
||
<div class="CHAPTER"> | ||
<h1>{{ page.title }}</h1> | ||
|
||
{{ content }} | ||
</div> | ||
|
||
<div class="NAVFOOTER"> | ||
<hr class="c1" width="100%" /> | ||
<table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0"> | ||
<tbody> | ||
<tr> | ||
<td valign="top" width="33%" align="left"> | ||
<a href="{{ page.previous }}" accesskey="P">Prev</a> | ||
</td> | ||
<td valign="top" width="34%" align="center"> | ||
<a href="index.html" accesskey="H">Home</a> | ||
</td> | ||
<td valign="top" width="33%" align="right"> | ||
<a href="{{ page.next }}" accesskey="N">Next</a> | ||
</td> | ||
</tr> | ||
<tr> | ||
<td valign="top" width="33%" align="left">{{ page.previoustitle }}</td> | ||
<td valign="top" width="34%" align="center"> </td> | ||
<td valign="top" width="33%" align="right">{{ page.nexttitle }}</td> | ||
</tr> | ||
</tbody> | ||
</table> | ||
</div> <!-- NAVFOOTER --> | ||
|
||
|
||
</div> <!-- docContent --> | ||
|
||
<div id="docComments"></div> | ||
|
||
<div id="docFooter"> | ||
<a class="navFooter" href="http://www.postgresql.org/about/privacypolicy">Privacy Policy</a> | | ||
<a class="navFooter" href="http://www.postgresql.org/about/">About PostgreSQL</a><br/> | ||
Copyright © 1996-{{ site.time | date: "%Y" }} The PostgreSQL Global Development Group | ||
</div> <!-- pgFooter --> | ||
</div> <!-- docContainer --> | ||
</div> <!-- docContainer --> | ||
</body> | ||
</html> |
@@ -0,0 +1,179 @@ | ||
--- | ||
layout: default_docs | ||
title: Chapter 7. Storing Binary Data | ||
header: Chapter 7. Storing Binary Data | ||
resource: media | ||
previoustitle: Chapter 6. Calling Stored Functions | ||
previous: callproc.html | ||
nexttitle: Chapter 8. JDBC escapes | ||
next: escapes.html | ||
--- | ||
|
||
PostgreSQL™ provides two distinct ways to store binary data. Binary data can be | ||
stored in a table using the data type BYTEA or by using the Large Object feature | ||
which stores the binary data in a separate table in a special format and refers | ||
to that table by storing a value of type OID in your table. | ||
|
||
In order to determine which method is appropriate you need to understand the | ||
limitations of each method. The BYTEA data type is not well suited for storing | ||
very large amounts of binary data. While a column of type BYTEA can hold up to | ||
1 GB of binary data, it would require a huge amount of memory to process such a | ||
large value. The Large Object method for storing binary data is better suited to | ||
storing very large values, but it has its own limitations. Specifically deleting | ||
a row that contains a Large Object reference does not delete the Large Object. | ||
Deleting the Large Object is a separate operation that needs to be performed. | ||
Large Objects also have some security issues since anyone connected to the | ||
database can view and/or modify any Large Object, even if they don't have | ||
permissions to view/update the row containing the Large Object reference. | ||
|
||
Version 7.2 was the first release of the JDBC driver that supports the BYTEA | ||
data type. The introduction of this functionality in 7.2 has introduced a change | ||
in behavior as compared to previous releases. Since 7.2, the methods `getBytes()`, | ||
`setBytes()`, `getBinaryStream()`, and `setBinaryStream()` operate on the BYTEA | ||
data type. In 7.1 and earlier, these methods operated on the OID data type | ||
associated with Large Objects. It is possible to revert the driver back to the | ||
old 7.1 behavior by setting the property `compatible` on the `Connection` object | ||
to the value `7.1`. More details on connection properties are available in the | ||
section called [“Connection Parameters”](connect.html#connection-parameters). | ||
|
||
To use the BYTEA data type you should simply use the `getBytes()`, `setBytes()`, | ||
`getBinaryStream()`, or `setBinaryStream()` methods. | ||
|
||
To use the Large Object functionality you can use either the `LargeObject` class | ||
provided by the PostgreSQL™ JDBC driver, or by using the `getBLOB()` and `setBLOB()` | ||
methods. | ||
|
||
### Important | ||
|
||
> You must access Large Objects within an SQL transaction block. You can start a | ||
transaction block by calling `setAutoCommit(false)`. | ||
[Example 7.1, “Processing Binary Data in JDBC”](binary-data.html#binary-data-example) | ||
contains some examples on how to process binary data using the PostgreSQL™ JDBC | ||
driver. | ||
|
||
<a name="binary-data-example"></a> | ||
***Example 7.1. Processing Binary Data in JDBC*** | ||
|
||
For example, suppose you have a table containing the file names of images and you | ||
also want to store the image in a BYTEA column: | ||
|
||
`CREATE TABLE images (imgname text, img bytea);` | ||
|
||
To insert an image, you would use: | ||
|
||
`File file = new File("myimage.gif");` | ||
`FileInputStream fis = new FileInputStream(file);` | ||
`PreparedStatement ps = conn.prepareStatement("INSERT INTO images VALUES (?, ?)");` | ||
`ps.setString(1, file.getName());` | ||
`ps.setBinaryStream(2, fis, (int)file.length());` | ||
`ps.executeUpdate();` | ||
`ps.close();` | ||
`fis.close();` | ||
|
||
Here, `setBinaryStream()` transfers a set number of bytes from a stream into the | ||
column of type BYTEA. This also could have been done using the `setBytes()` method | ||
if the contents of the image was already in a `byte[]`. | ||
|
||
### Note | ||
|
||
> The length parameter to `setBinaryStream` must be correct. There is no way to | ||
indicate that the stream is of unknown length. If you are in this situation, you | ||
must read the stream yourself into temporary storage and determine the length. | ||
Now with the correct length you may send the data from temporary storage on to | ||
the driver. | ||
Retrieving an image is even easier. (We use `PreparedStatement` here, but the | ||
`Statement` class can equally be used.) | ||
|
||
`PreparedStatement ps = conn.prepareStatement("SELECT img FROM images WHERE imgname = ?");` | ||
`ps.setString(1, "myimage.gif");` | ||
`ResultSet rs = ps.executeQuery();` | ||
`while (rs.next())` | ||
`{` | ||
`byte[] imgBytes = rs.getBytes(1);` | ||
`// use the data in some way here` | ||
`}` | ||
`rs.close();` | ||
`ps.close();` | ||
|
||
Here the binary data was retrieved as an `byte[]`. You could have used a | ||
`InputStream` object instead. | ||
|
||
Alternatively you could be storing a very large file and want to use the | ||
`LargeObject` API to store the file: | ||
|
||
`CREATE TABLE imageslo (imgname text, imgoid oid);` | ||
|
||
To insert an image, you would use: | ||
|
||
|
||
`// All LargeObject API calls must be within a transaction block` | ||
`conn.setAutoCommit(false);``<br /> | ||
`// Get the Large Object Manager to perform operations with` | ||
`LargeObjectManager lobj = conn.unwrap(org.postgresql.PGConnection.class).getLargeObjectAPI();`<br /> | ||
`// Create a new large object` | ||
`long oid = lobj.createLO(LargeObjectManager.READ | LargeObjectManager.WRITE);`<br /> | ||
`// Open the large object for writing` | ||
`LargeObject obj = lobj.open(oid, LargeObjectManager.WRITE);`<br /> | ||
`// Now open the file` | ||
`File file = new File("myimage.gif");` | ||
`FileInputStream fis = new FileInputStream(file);`<br /> | ||
`// Copy the data from the file to the large object` | ||
`byte buf[] = new byte[2048];` | ||
`int s, tl = 0;` | ||
`while ((s = fis.read(buf, 0, 2048)) > 0)` | ||
`{` | ||
`obj.write(buf, 0, s);` | ||
`tl += s;` | ||
`}`<br /> | ||
|
||
`// Close the large object` | ||
`obj.close();`<br /> | ||
|
||
`// Now insert the row into imageslo` | ||
`PreparedStatement ps = conn.prepareStatement("INSERT INTO imageslo VALUES (?, ?)");` | ||
`ps.setString(1, file.getName());` | ||
`ps.setLong(2, oid);` | ||
`ps.executeUpdate();` | ||
`ps.close();` | ||
`fis.close();`<br /> | ||
|
||
`// Finally, commit the transaction.` | ||
`conn.commit();` | ||
|
||
Retrieving the image from the Large Object: | ||
|
||
`// All LargeObject API calls must be within a transaction block` | ||
`conn.setAutoCommit(false);`<br /> | ||
|
||
`// Get the Large Object Manager to perform operations with` | ||
`LargeObjectManager lobj = conn.unwrap(org.postgresql.PGConnection.class).getLargeObjectAPI();`<br /> | ||
|
||
`PreparedStatement ps = conn.prepareStatement("SELECT imgoid FROM imageslo WHERE imgname = ?");` | ||
`ps.setString(1, "myimage.gif");` | ||
`ResultSet rs = ps.executeQuery();` | ||
`while (rs.next())` | ||
`{` | ||
`// Open the large object for reading` | ||
`long oid = rs.getLong(1);` | ||
`LargeObject obj = lobj.open(oid, LargeObjectManager.READ);`<br /> | ||
|
||
`// Read the data` | ||
`byte buf[] = new byte[obj.size()];` | ||
`obj.read(buf, 0, obj.size());` | ||
`// Do something with the data read here`<br /> | ||
|
||
`// Close the object` | ||
`obj.close();` | ||
`}` | ||
`rs.close();` | ||
`ps.close();`<br /> | ||
|
||
`// Finally, commit the transaction.` | ||
`conn.commit();` |
Oops, something went wrong.