FIND-DATABASE
Prev | Connection and Initialisation | Next

## Name

FIND-DATABASE — >Locate a database object through it's name.Function

## Syntax

    find-database database &optional errorp => result

## Arguments and Values

`database`

  A database object or a string, denoting a database name.

`errorp`

  A generalized boolean. Defaults to t.

`db-type`

  A keyword symbol denoting a known database back-end.

result

  Either a database object, or, if `errorp` is `NIL`, possibly `NIL`.

## Description

`find-database` locates an active database object given the specification in `database`. If `database` is an object of type database, `find-database` returns this. Otherwise it will search the active databases as indicated by the list returned by `connected-databases` for a database of type `db-type` whose name (as returned by `database-name` is equal as per `string=` to the string passed as `database`. If it succeeds, it returns the first database found.

If `db-type` is `NIL` all databases matching the string `database` are considered. If no matching databases are found and `errorp` is `NIL` then `NIL` is returned. If `errorp` is `NIL` and one or more matching databases are found, then the most recently connected database is returned as a first value and the number of matching databases is returned as a second value. If no, or more than one, matching databases are found and `errorp` is true, an error is signalled.

## Examples

    (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
    => "dent/newesim/dent"
    (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
    => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
    (database-name *default-database*)
    => "dent/newesim/dent"

    (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
    => "/template1/dent"
    (connect '(nil "template1" "dent" nil) :database-type :postgresql)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (database-name *default-database*)
    => "/template1/dent"

    (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
    => "www.pmsf.de/template1/dent"

    (find-database "dent/newesim/dent")
    => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
    (find-database "/template1/dent")
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
    (find-database "www.pmsf.de/template1/dent" nil)
    => NIL
    (find-database **)
    => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>

## Side Effects

None.

## Affected By

`connected-databases`

## Exceptional Situations

Will signal an error of type clsql-error if no matching database can be found, and `errorp` is true. Will signal an error if the value of `database` is neither an object of type database nor a string.

## See Also

`database-name`
`database-name-from-spec`
`disconnect`
`connect`
`status`
`connected-databases`

## Notes

The `db-type` keyword argument to `find-database` is a CLSQL extension.

Prev | Up | Next
DISCONNECT-POOLED | Home | INITIALIZE-DATABASE-TYPE