Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OpenXPKI::Server::DataUser(Contributed Perl DocumOpenXPKI::Server::Database(3)

Name
       OpenXPKI::Server::Database - Handles database connections and
       encapsulates DB specific	drivers/functions.

Description
       This class contains the API to interact with the	configured OpenXPKI
       database.

   Database drivers
       While OpenXPKI supports several database	types out of the box it	still
       allows you to include new DBMS specific drivers without the need	to
       change existing code.

       For more	details	see OpenXPKI::Server::Database::Role::Driver.

   Class structure
		.----------------------------.
	   .----| OpenXPKI::Server::Database |---.--------------------.
	   |	'----------------------------'	 |		      |
	   |		       |		 |		      |
	   |		       |		 v		      v
	   |		       |      .---------------------. .---------------.
	   |		 .-----'      |	SQL::Abstract::More | |	DBIx::Handler |
	   |		 |	      '---------------------' '---------------'
	   |		 |			 .
	   |		 v		     injected
	   |  .---------------------.		 .
	   |  |	O:S:D::QueryBuilder |<...........'
	   |  '---------------------'
	   |		 |     .--------------.
	   |		 '---->| O:S:D::Query |
	   |		       '--------------'
	   |
	   |  .------------------.
	   '->|	O:S:D::Driver::* |
	      '------------------'
		.
	      consumes
		.    .---------------------.
		....>| O:S:D::Role::Driver |
		.    '---------------------'
		.    .------------------------------.	 .--------------------------------.
		....>| O:S:D::Role::SequenceSupport | or | O:S:D::Role::SequenceEmulation |
		.    '------------------------------'	 '--------------------------------'
		.    .------------------------------.	 .--------------------------------.
		'...>| O:S:D::Role::MergeSupport    | or | O:S:D::Role::MergeEmulation	  |
		     '------------------------------'	 '--------------------------------'

Attributes
   Constructor parameters
       o   log - Log object (OpenXPKI::Server::Log, required)

       o   db_params - HashRef with parameters for the DBI data	source name
	   string.

	   Required keys in this hash:

	   o   type - last part	of a package in	the
	       "OpenXPKI::Server::Database::Driver::*" namespace. (Str,
	       required)

	   o   Any of the "Constructor parameters" in
	       OpenXPKI::Server::Database::Role::Driver

	   o   Additional parameters required by the specific driver

   Others
       o   driver - database specific driver instance (consumer	of
	   OpenXPKI::Server::Database::Role::Driver)

       o   query_builder - OpenXPKI query builder to create abstract SQL
	   queries (OpenXPKI::Server::Database::QueryBuilder)

	   Usage:

	       my $query = $db->query_builder->select(
		   from	=> 'certificate',
		   columns  => [ 'identifier' ],
		   where => { pki_realm	=> 'ca-one' },
	       );
	       # returns an OpenXPKI::Server::Database::Query object

       o   db_version -	database version, equals the result of
	   "$dbh->get_version(...)" (Str)

       o   sqlam - low level SQL query builder (internal work horse, an
	   instance of SQL::Abstract::More)

Methods
   new
       Constructor.

       Named parameters: see attributes	section	above.

   select
       Selects rows from the database and returns the results as a DBI::st
       statement handle.

       Please note that	"NULL" values will be converted	to Perl	"undef".

       For parameters see "select" in
       OpenXPKI::Server::Database::QueryBuilder.

   select_one
       Selects one row from the	database and returns the results as a HashRef
       (column name => value) by calling "$sth->fetchrow_hashref".

       For parameters see "select" in
       OpenXPKI::Server::Database::QueryBuilder.

       Returns "undef" if the query had	no results.

       Please note that	"NULL" values will be converted	to Perl	"undef".

   insert
       Inserts rows into the database and returns the results as a DBI::st
       statement handle.

       Please note that	"NULL" values will be converted	to Perl	"undef".

       For parameters see "insert" in
       OpenXPKI::Server::Database::QueryBuilder.

   update
       Updates rows in the database and	returns	the results as a DBI::st
       statement handle.

       Please note that	"NULL" values will be converted	to Perl	"undef".

       For parameters see "update" in
       OpenXPKI::Server::Database::QueryBuilder.

   merge
       Either directly executes	or emulates an SQL MERGE (you could also call
       it REPLACE) function and	returns	the results as a DBI::st statement
       handle.

       Named parameters:

       o   into	- Table	name (Str, required)

       o   set - Columns that are always set (INSERT or	UPDATE). Hash with
	   column name / value pairs.

	   Please note that "undef" is interpreted as "NULL" (HashRef,
	   required)

       o   set_once - Columns that are only set	on INSERT (additional to those
	   in the "where" parameter. Hash with column name / value pairs.

	   Please note that "undef" is interpreted as "NULL" (HashRef,
	   required)

       o   where - WHERE clause	specification that must	contain	the PRIMARY
	   KEY columns and only	allows "AND" and "equal" operators: "<{	col1
	   =" val1, col2 => val2 }>> (HashRef)

	   The values from the WHERE clause are	also inserted if the row does
	   not exist (together with those from "set_once")!

   delete
       Deletes rows in the database and	returns	the results as a DBI::st
       statement handle.

       For parameters see "delete" in
       OpenXPKI::Server::Database::QueryBuilder.

   start_txn
       Records the start of a new transaction (i.e. sets a flag) without
       database	interaction.

       If the flag was already set (= another transaction is running), a
       "ROLLBACK" is performed first and an error message is logged.

       Please note that	after a	"fork()" the flag is be	reset as the "DBI"
       handle is also reset (so	there cannot be	a running transaction).

   in_txn
       Returns "true" if a transaction is currently running, i.e. after
       "start_txn" was called but before "commit" or "rollback"	where called.

   commit
       Commits a transaction.

       Logs an error if	"start_txn" was	not called first.

   rollback
       Rolls back a transaction.

       Logs an error if	"start_txn" was	not called first.

Low level methods
       The following methods allow more	fine grained control over the query
       processing.

   dbh
       Returns a fork safe DBI handle. Connects	to the database	if neccessary.

       To remain fork safe DO NOT CACHE	this (also do not convert into a lazy
       attribute).

   run
       Executes	the given query	and returns a DBI statement handle.

	   my $sth = $db->run($query) or die "Error executing query: $@";

       Parameters:

       o   $query - query to run (either a OpenXPKI::Server::Database::Query
	   or a	literal	SQL string)

   disconnect
       Disconnects from	the database. Might be useful to e.g. remove file
       locks when using	SQLite.

perl v5.24.1			  2017-07-03	 OpenXPKI::Server::Database(3)

Name | Description | Attributes | Methods | Low level methods

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OpenXPKI::Server::Database&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help