Add Connection::info(), conn::Info and conn::ServerType to get connec…

…tion information

ChangeLog.md

@@ -2,6 +2,10 @@
 
 ## 0.6.3 (2024-XX-XX)
 
+New features:
+
+* Add [`Connection::info()`], [`conn::Info`] and [`conn::ServerType`] to get connection information
+
 Fixed Issues:
 
 * Fix panic when invalid argument Error is displayed
@@ -472,12 +476,15 @@ Incompatible changes:
 [`Collection::values()`]: https://www.jiubao.org/rust-oracle/oracle/sql_type/struct.Collection.html#method.values
 [`ColumnIndex`]: https://www.jiubao.org/rust-oracle/oracle/trait.ColumnIndex.html
 [`ColumnInfo::name()`]: https://www.jiubao.org/rust-oracle/oracle/struct.ColumnInfo.html#method.name
+[`conn::Info`]: https://www.jiubao.org/rust-oracle/oracle/conn/struct.Info.html
+[`conn::ServerType`]: https://www.jiubao.org/rust-oracle/oracle/conn/enum.ServerType.html
 [`Connection`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html
 [`Connection::connect()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.connect
 [`Connection::call_timeout()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.call_timeout
 [`Connection::close_with_mode()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.close_with_mode
 [`Connection::execute()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.execute
 [`Connection::execute_named()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.execute_named
+[`Connection::info()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.info
 [`Connection::is_new_connection()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.is_new_connection
 [`Connection::last_warning()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.last_warning
 [`Connection::object_type()`]: https://www.jiubao.org/rust-oracle/oracle/struct.Connection.html#method.object_type

src/conn.rs

@@ -3,7 +3,7 @@
 // URL: https://github.com/kubo/rust-oracle
 //
 //-----------------------------------------------------------------------------
-// Copyright (c) 2017-2021 Kubo Takehiro <[email protected]>. All rights reserved.
+// Copyright (c) 2017-2024 Kubo Takehiro <[email protected]>. All rights reserved.
 // This program is free software: you can modify it and/or redistribute it
 // under the terms of:
 //
@@ -17,8 +17,11 @@
 //!
 //! Some types at the top-level module will move here in future.
 use crate::binding::*;
+use crate::to_rust_str;
 #[cfg(doc)]
 use crate::Connection;
+use crate::Error;
+use crate::Result;
 
 /// The mode to use when closing connections to the database
 ///
@@ -55,3 +58,90 @@ impl Purity {
         }
     }
 }
+
+/// The type of server process associated with a connection
+///
+/// It is only available with Oracle Client libraries 23.4 or higher.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+pub enum ServerType {
+    /// A dedicated server process is being used with the connection.
+    Dedicated,
+    /// A pooled server process (DRCP) is being used with the connection.
+    Pooled,
+    /// A shared server process is being used with the connection.
+    Shared,
+    /// The type of server process is unknown.
+    Unknown,
+}
+
+impl ServerType {
+    pub(crate) fn from_dpi(server_type: u8) -> Result<ServerType> {
+        match server_type as u32 {
+            DPI_SERVER_TYPE_DEDICATED => Ok(ServerType::Dedicated),
+            DPI_SERVER_TYPE_POOLED => Ok(ServerType::Pooled),
+            DPI_SERVER_TYPE_SHARED => Ok(ServerType::Shared),
+            DPI_SERVER_TYPE_UNKNOWN => Ok(ServerType::Unknown),
+            _ => Err(Error::internal_error(format!(
+                "Unknown dpiServerType {}",
+                server_type
+            ))),
+        }
+    }
+}
+
+/// Information about a connection
+///
+/// This is a return value of [`Connection::info()`].
+#[non_exhaustive]
+#[derive(Debug, Clone, PartialEq)]
+pub struct Info {
+    /// The name of the Oracle Database Domain name associated with the connection
+    ///
+    /// This is the same value returned by the SQL expression
+    /// `SELECT VALUE FROM V$PARAMETER WHERE NAME = 'db_domain'`.
+    pub db_domain: String,
+
+    /// The Oracle Database name associated with the connection
+    pub db_name: String,
+
+    /// The Oracle Database instance name associated with the connection
+    pub instance_name: String,
+
+    /// The Oracle Database service name associated with the connection
+    ///
+    /// This is the same value returned by the SQL expression
+    /// `SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL`.
+    pub service_name: String,
+
+    /// The maximum length of identifiers (in bytes) supported by the
+    /// database to which the connection has been established
+    ///
+    /// See [Database Object Naming Rules](https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-75337742-67FD-4EC0-985F-741C93D918DA).
+    pub max_identifier_length: u32,
+
+    /// The maximum number of cursors that can be opened
+    ///
+    /// This is the same value returned by the SQL expression
+    /// `SELECT VALUE FROM V$PARAMETER WHERE NAME = 'open_cursors'`.
+    pub max_open_cursors: u32,
+
+    /// The type of server process used by the connection
+    ///
+    /// This is only available with Oracle Client libraries 23.4 or higher.
+    /// Otherwise, it is always `ServerType::Unknown`.
+    pub server_type: ServerType,
+}
+
+impl Info {
+    pub(crate) fn from_dpi(info: &dpiConnInfo) -> Result<Info> {
+        Ok(Info {
+            db_domain: to_rust_str(info.dbDomain, info.dbDomainLength),
+            db_name: to_rust_str(info.dbName, info.dbNameLength),
+            instance_name: to_rust_str(info.instanceName, info.instanceNameLength),
+            service_name: to_rust_str(info.serviceName, info.serviceNameLength),
+            max_identifier_length: info.maxIdentifierLength,
+            max_open_cursors: info.maxOpenCursors,
+            server_type: ServerType::from_dpi(info.serverType)?,
+        })
+    }
+}

src/connection.rs

@@ -3,7 +3,7 @@
 // URL: https://github.com/kubo/rust-oracle
 //
 //-----------------------------------------------------------------------------
-// Copyright (c) 2017-2021 Kubo Takehiro <[email protected]>. All rights reserved.
+// Copyright (c) 2017-2024 Kubo Takehiro <[email protected]>. All rights reserved.
 // This program is free software: you can modify it and/or redistribute it
 // under the terms of:
 //
@@ -25,7 +25,7 @@ use std::time::Duration;
 
 use crate::binding::*;
 use crate::chkerr;
-use crate::conn::{CloseMode, Purity};
+use crate::conn::{CloseMode, Info, Purity};
 use crate::error::DPI_ERR_NOT_CONNECTED;
 use crate::oci_attr::data_type::{AttrValue, DataType};
 use crate::oci_attr::handle::ConnHandle;
@@ -1740,6 +1740,28 @@ impl Connection {
         self.conn.is_new_connection
     }
 
+    /// Returns information about the connection
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use oracle::Error;
+    /// # use oracle::test_util;
+    /// # let conn = test_util::connect()?;
+    /// let info = conn.info()?;
+    /// let service_name = conn.query_row_as::<String>("SELECT SYS_CONTEXT('USERENV', 'SERVICE_NAME') FROM DUAL", &[])?;
+    /// assert_eq!(info.service_name, service_name);
+    /// # Ok::<(), Error>(())
+    /// ```
+    pub fn info(&self) -> Result<Info> {
+        let mut info = MaybeUninit::uninit();
+        chkerr!(
+            self.ctxt(),
+            dpiConn_getInfo(self.handle(), info.as_mut_ptr())
+        );
+        Info::from_dpi(unsafe { &info.assume_init() })
+    }
+
     /// Gets an OCI handle attribute corresponding to the specified type parameter
     /// See the [`oci_attr` module][crate::oci_attr] for details.
     pub fn oci_attr<T>(&self) -> Result<<<T::DataType as DataType>::Type as ToOwned>::Owned>