Skip to content

Commit d2e9f4e

Browse files
tomix26tomix26
committed
update readme
1 parent b6593d7 commit d2e9f4e

File tree

1 file changed

+112
-27
lines changed

1 file changed

+112
-27
lines changed

‎README.md‎

Lines changed: 112 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,35 @@
1-
OpenTable Embedded PostgreSQL Component
2-
=======================================
1+
## Introduction
32

4-
Allows embedding PostgreSQL into Java application code with
5-
no external dependencies. Excellent for allowing you to unit
6-
test with a "real" Postgres without requiring end users to install
7-
and set up a database cluster.
3+
This project is a fork of [OpenTable Embedded PostgreSQL Component](https://github.com/opentable/otj-pg-embedded) created due to the inactivity of the maintainers.
4+
5+
The library allows embedding PostgreSQL into Java application code with no external dependencies.
6+
Excellent for allowing you to unit test with a "real" Postgres without requiring end users to install and set up a database cluster.
7+
8+
If you are using `Spring` or `Spring Boot` framework you can also consider using the specialized [embedded-database-spring-test](https://github.com/zonkyio/embedded-database-spring-test) project.
9+
10+
## Features
11+
12+
* All features of `com.opentable:otj-pg-embedded:0.12.6`
13+
* Configurable version of [PostgreSQL binaries](https://github.com/zonkyio/embedded-postgres-binaries)
14+
* Support for running inside Docker, including Alpine Linux
15+
* Fixed the logging of initdb process ([#83](https://github.com/opentable/otj-pg-embedded/pull/83))
16+
* Fixed the caching of prepared databases ([#85](https://github.com/opentable/otj-pg-embedded/pull/85))
17+
* Improved extracting postgres archives on Windows platform ([#84](https://github.com/opentable/otj-pg-embedded/pull/84))
18+
19+
## Maven Configuration
20+
21+
Add the following Maven dependency:
22+
23+
```xml
24+
<dependency>
25+
<groupId>io.zonky.test</groupId>
26+
<artifactId>embedded-postgres</artifactId>
27+
<version>1.2.1</version>
28+
<scope>test</scope>
29+
</dependency>
30+
```
31+
32+
The default version of the embedded postgres is `PostgreSQL 10.6`, but you can change it by following the instructions described in [Postgres version](#postgres-version).
833

934
## Basic Usage
1035

@@ -38,31 +63,91 @@ independent databases gives you.
3863

3964
## Postgres version
4065

41-
The JAR file contains bundled version of Postgres. You can pass different Postgres version by implementing [`PgBinaryResolver`](src/main/java/io/zonky/test/db/postgres/embedded/PgBinaryResolver.java).
66+
The default version of the embedded postgres is `PostgreSQL 10.6`, but it can be changed by importing `embedded-postgres-binaries-bom` in a required version into your dependency management section.
67+
68+
```xml
69+
<dependencyManagement>
70+
<dependencies>
71+
<dependency>
72+
<groupId>io.zonky.test.postgres</groupId>
73+
<artifactId>embedded-postgres-binaries-bom</artifactId>
74+
<version>11.1.0</version>
75+
<type>pom</type>
76+
<scope>import</scope>
77+
</dependency>
78+
</dependencies>
79+
</dependencyManagement>
80+
```
81+
82+
A list of all available versions of postgres binaries is here: https://mvnrepository.com/artifact/io.zonky.test.postgres/embedded-postgres-binaries-bom
4283

43-
Example:
44-
```java
45-
class ClasspathBinaryResolver implements PgBinaryResolver {
46-
public InputStream getPgBinary(String system, String machineHardware) throws IOException {
47-
ClassPathResource resource = new ClassPathResource(format("postgresql-%s-%s.txz", system, machineHardware));
48-
return resource.getInputStream();
49-
}
50-
}
51-
52-
EmbeddedPostgreSQL
53-
.builder()
54-
.setPgBinaryResolver(new ClasspathBinaryResolver())
55-
.start();
84+
Note that the release cycle of the postgres binaries is independent of the release cycle of this library, so you can upgrade to a new version of postgres binaries immediately after it is released.
85+
86+
## Additional architectures
5687

88+
By default, only the support for `amd64` architecture is enabled.
89+
Support for other architectures can be enabled by adding the corresponding Maven dependencies as shown in the example below.
90+
91+
```xml
92+
<dependency>
93+
<groupId>io.zonky.test.postgres</groupId>
94+
<artifactId>embedded-postgres-binaries-linux-i386</artifactId>
95+
<scope>test</scope>
96+
</dependency>
5797
```
5898

59-
## Windows
99+
**Supported platforms:** `Darwin`, `Windows`, `Linux`, `Alpine Linux`
100+
**Supported architectures:** `amd64`, `i386`, `arm32v6`, `arm32v7`, `arm64v8`, `ppc64le`
101+
102+
Note that not all architectures are supported by all platforms, look here for an exhaustive list of all available artifacts: https://mvnrepository.com/artifact/io.zonky.test.postgres
103+
104+
Since `PostgreSQL 10.0`, there are additional artifacts with `alpine-lite` suffix. These artifacts contain postgres binaries for Alpine Linux with disabled [ICU support](https://blog.2ndquadrant.com/icu-support-postgresql-10/) for further size reduction.
105+
106+
## Troubleshooting
107+
108+
### Process [/tmp/embedded-pg/PG-XYZ/bin/initdb, ...] failed
109+
110+
Try to remove `/tmp/embedded-pg/PG-XYZ` directory containing temporary binaries of the embedded postgres database. That should solve the problem.
111+
112+
### Running tests on Windows does not work
113+
114+
You probably need to install the [Microsoft Visual C++ 2013 Redistributable Package](https://support.microsoft.com/en-us/help/3179560/update-for-visual-c-2013-and-visual-c-redistributable-package). The version 2013 is important, installation of other versions will not help. More detailed is the problem discussed [here](https://github.com/opentable/otj-pg-embedded/issues/65).
115+
116+
### Running tests inside Docker does not work
117+
118+
Running build inside Docker is fully supported, including Alpine Linux. But you must keep in mind that the **PostgreSQL database must be run under a non-root user**. Otherwise, the database does not start and fails with an error.
119+
120+
So be sure to use a docker image that uses a non-root user, or you can use any of the following Dockerfiles to build your own image.
121+
122+
<details>
123+
<summary>Standard Dockerfile</summary>
124+
125+
```dockerfile
126+
FROM openjdk:8-jdk
127+
128+
RUN groupadd --system --gid 1000 test
129+
RUN useradd --system --gid test --uid 1000 --shell /bin/bash --create-home test
130+
131+
USER test
132+
WORKDIR /home/test
133+
```
134+
135+
</details>
60136

61-
If you experience difficulty running `otj-pg-embedded` tests on Windows, make sure
62-
you've installed the appropriate MFC redistributables.
137+
<details>
138+
<summary>Alpine Dockerfile</summary>
139+
140+
```dockerfile
141+
FROM openjdk:8-jdk-alpine
142+
143+
RUN addgroup -S -g 1000 test
144+
RUN adduser -D -S -G test -u 1000 -s /bin/ash test
145+
146+
USER test
147+
WORKDIR /home/test
148+
```
63149

64-
* [Microsoft Site](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads])
65-
* [Github issue discussing this](https://github.com/opentable/otj-pg-embedded/issues/65)
150+
</details>
66151

67-
----
68-
Copyright (C) 2017 OpenTable, Inc
152+
## License
153+
The project is released under version 2.0 of the [Apache License](http://www.apache.org/licenses/LICENSE-2.0.html).

0 commit comments

Comments
 (0)