extensions/entitystore-sqlkv/src/docs/es-sqlkv.txt

///////////////////////////////////////////////////////////////
 * 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.
///////////////////////////////////////////////////////////////

[[extension-es-sqlkv, SQL Key/Value EntityStore]]
= SQL Key/Value EntityStore =

[devstatus]
--------------
source=extensions/entitystore-sqlkv/dev-status.xml
--------------

EntityStore service backed by a SQL database with a simple schema where entities are stored in a key/value fashion.

This extension fully leverage the <<library-sql>> meaning that you must use it to assemble your DataSource and that you
get <<library-circuitbreaker,Circuit Breaker>> and <<library-jmx, JMX>> integration for free.

The database schema is managed using <<library-sql-liquibase>>.

TIP: See the <<sample-sql-support>> that demonstrate combined use of <<library-sql>>, <<extension-es-sql>> and
<<extension-indexing-sql>>.

The following SQL databases are supported:

- http://www.postgresql.org/[PostgreSQL]
- http://www.mysql.com/[MySQL] and http://mariadb.org/[MariaDB]
- http://www.sqlite.org/[SQLite]
- http://www.h2database.com/[H2 Database Engine]
- http://db.apache.org/derby/[Apache Derby] and http://www.oracle.com/technetwork/java/javadb/overview/index.htm[Oracle JavaDB]

Each entity state is stored as a single row so maximum number of entities is the maximum number of rows per table
supported by the underlying SQL database.

include::../../build/docs/buildinfo/artifact.txt[]

== Configuration ==

Here are the available configuration properties:

[snippet,java]
----
source=extensions/entitystore-sqlkv/src/main/java/org/apache/polygene/entitystore/sql/SQLMapEntityStoreConfiguration.java
tag=config
----

The assembly snippets below show the DataSource assembly alongside the SQL EntityStore assembly. Remember to configure
the DataSource properly, see <<library-sql>> and <<howto-configure-service>>.


== PostgreSQL ==

Maximum number of entities is unlimited.

Assembly is done using the provided Assembler:

[snippet,java]
----
source=extensions/entitystore-sqlkv/src/test/java/org/apache/polygene/entitystore/sql/PostgreSQLEntityStoreTest.java
tag=assembly
----

Sample DataSource configuration defaults:

[source,java]
----
include::../test/resources/postgresql-datasource.properties[]
----


== MySQL and MariaDB ==

Maximum number of entities depends on the choosen storage engine.

Assembly is done using the provided Assembler:

[snippet,java]
----
source=extensions/entitystore-sqlkv/src/test/java/org/apache/polygene/entitystore/sql/MySQLEntityStoreTest.java
tag=assembly
----

Sample DataSource configuration defaults:

[source,java]
----
include::../test/resources/mysql-datasource.properties[]
----


== SQLite ==

Maximum number of entities is unlimited.

The http://www.xerial.org/trac/Xerial/wiki/SQLiteJDBC[Xerial SQLite JDBC] driver is recommended.
It provides native support on Linux, Windows and MaxOSX, pure Java on other OSes.

Assembly is done using the provided Assembler:

[snippet,java]
----
source=extensions/entitystore-sqlkv/src/test/java/org/apache/polygene/entitystore/sql/SQLiteEntityStoreTest.java
tag=assembly
----

Sample DataSource configuration defaults:

[source,java]
----
include::../test/resources/sqlite-datasource.properties[]
----


== H2 Database Engine ==

Maximum number of entities is 2^64.

Assembly is done using the provided Assembler:

[snippet,java]
----
source=extensions/entitystore-sqlkv/src/test/java/org/apache/polygene/entitystore/sql/H2SQLEntityStoreTest.java
tag=assembly
----

Sample DataSource configuration defaults:

[source,java]
----
include::../test/resources/h2-datasource.properties[]
----



== Apache Derby and Oracle JavaDB ==

Maximum number of entities is unlimited.

Assembly is done using the provided Assembler:

[snippet,java]
----
source=extensions/entitystore-sqlkv/src/test/java/org/apache/polygene/entitystore/sql/DerbySQLEntityStoreTest.java
tag=assembly
----

Sample DataSource configuration defaults:

[source,java]
----
include::../test/resources/derby-datasource.properties[]
----