oracle/
conn.rs

1// Rust-oracle - Rust binding for Oracle database
2//
3// URL: https://github.com/kubo/rust-oracle
4//
5//-----------------------------------------------------------------------------
6// Copyright (c) 2017-2024 Kubo Takehiro <kubo@jiubao.org>. All rights reserved.
7// This program is free software: you can modify it and/or redistribute it
8// under the terms of:
9//
10// (i)  the Universal Permissive License v 1.0 or at your option, any
11//      later version (http://oss.oracle.com/licenses/upl); and/or
12//
13// (ii) the Apache License v 2.0. (http://www.apache.org/licenses/LICENSE-2.0)
14//-----------------------------------------------------------------------------
15
16//! Type definitions for connection
17//!
18//! Some types at the top-level module will move here in future.
19use crate::to_rust_str;
20#[cfg(doc)]
21use crate::Connection;
22use crate::Error;
23use crate::Result;
24use odpic_sys::*;
25
26/// The mode to use when closing connections to the database
27///
28/// See [`Connection::close_with_mode`].
29#[derive(Debug, Copy, Clone, PartialEq, Eq)]
30pub enum CloseMode<'a> {
31    /// The connection is returned to the connection pool for
32    /// future use.
33    Default,
34
35    /// Causes the connection to be dropped from the connection
36    /// pool.
37    Drop,
38
39    /// Causes the connection to be tagged with the tag information.
40    /// An empty tag `""` will cause the tag to be cleared.
41    Retag(&'a str),
42}
43
44#[derive(Debug, Copy, Clone, PartialEq, Eq)]
45/// [Session Purity](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-12410EEC-FE79-42E2-8F6B-EAA9EDA59665)
46pub enum Purity {
47    /// Must use a new session
48    New,
49    /// Reuse a pooled session
50    Self_,
51}
52
53impl Purity {
54    pub(crate) fn to_dpi(self) -> dpiPurity {
55        match self {
56            Purity::New => DPI_PURITY_NEW,
57            Purity::Self_ => DPI_PURITY_SELF,
58        }
59    }
60}
61
62/// The type of server process associated with a connection
63///
64/// It is only available with Oracle Client libraries 23.4 or higher.
65#[derive(Debug, Copy, Clone, PartialEq, Eq)]
66pub enum ServerType {
67    /// A dedicated server process is being used with the connection.
68    Dedicated,
69    /// A pooled server process (DRCP) is being used with the connection.
70    Pooled,
71    /// A shared server process is being used with the connection.
72    Shared,
73    /// The type of server process is unknown.
74    Unknown,
75}
76
77impl ServerType {
78    pub(crate) fn from_dpi(server_type: u8) -> Result<ServerType> {
79        match server_type {
80            DPI_SERVER_TYPE_DEDICATED => Ok(ServerType::Dedicated),
81            DPI_SERVER_TYPE_POOLED => Ok(ServerType::Pooled),
82            DPI_SERVER_TYPE_SHARED => Ok(ServerType::Shared),
83            DPI_SERVER_TYPE_UNKNOWN => Ok(ServerType::Unknown),
84            _ => Err(Error::internal_error(format!(
85                "Unknown dpiServerType {}",
86                server_type
87            ))),
88        }
89    }
90}
91
92/// Information about a connection
93///
94/// This is a return value of [`Connection::info()`].
95#[non_exhaustive]
96#[derive(Debug, Clone, PartialEq)]
97pub struct Info {
98    /// The name of the Oracle Database Domain name associated with the connection
99    ///
100    /// This is the same value returned by the SQL expression
101    /// `SELECT VALUE FROM V$PARAMETER WHERE NAME = 'db_domain'`.
102    pub db_domain: String,
103
104    /// The Oracle Database name associated with the connection
105    ///
106    /// This is the same value returned by the SQL expression
107    /// `SELECT NAME FROM V$DATABASE`.
108    /// Note the values may have different cases.
109    pub db_name: String,
110
111    /// The Oracle Database instance name associated with the connection
112    ///
113    /// This is the same value returned by the SQL expression
114    /// `SELECT SYS_CONTEXT('USERENV', 'INSTANCE_NAME') FROM DUAL`.
115    /// Note the values may have different cases.
116    pub instance_name: String,
117
118    /// The Oracle Database service name associated with the connection
119    ///
120    /// This is the same value returned by the SQL expression
121    /// `SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL`.
122    pub service_name: String,
123
124    /// The maximum length of identifiers (in bytes) supported by the
125    /// database to which the connection has been established
126    ///
127    /// See [Database Object Naming Rules](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-75337742-67FD-4EC0-985F-741C93D918DA).
128    pub max_identifier_length: u32,
129
130    /// The maximum number of cursors that can be opened
131    ///
132    /// This is the same value returned by the SQL expression
133    /// `SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'`.
134    pub max_open_cursors: u32,
135
136    /// The type of server process used by the connection
137    ///
138    /// This is only available with Oracle Client libraries 23.4 or higher.
139    /// Otherwise, it is always `ServerType::Unknown`.
140    pub server_type: ServerType,
141}
142
143impl Info {
144    pub(crate) fn from_dpi(info: &dpiConnInfo) -> Result<Info> {
145        Ok(Info {
146            db_domain: to_rust_str(info.dbDomain, info.dbDomainLength),
147            db_name: to_rust_str(info.dbName, info.dbNameLength),
148            instance_name: to_rust_str(info.instanceName, info.instanceNameLength),
149            service_name: to_rust_str(info.serviceName, info.serviceNameLength),
150            max_identifier_length: info.maxIdentifierLength,
151            max_open_cursors: info.maxOpenCursors,
152            server_type: ServerType::from_dpi(info.serverType)?,
153        })
154    }
155}
oracle/conn.rs

oracle/
conn.rs
