Refactor entire codebase and rewrite documentation
This commit is contained in:
@@ -1,140 +1,43 @@
|
||||
import Foundation
|
||||
|
||||
extension Connection {
|
||||
/// The `Location` enum represents different locations for a SQLite database.
|
||||
/// A location specifying where the SQLite database is stored or created.
|
||||
///
|
||||
/// This enum allows you to specify how and where a SQLite database will be stored or accessed.
|
||||
/// You can choose from three options:
|
||||
///
|
||||
/// - **File**: A database located at a specified file path or URI. This option is suitable
|
||||
/// for persistent storage and can reference any valid file location in the filesystem or
|
||||
/// a URI.
|
||||
///
|
||||
/// - **In-Memory**: An in-memory database that exists only in RAM. This option is useful
|
||||
/// for temporary data processing, testing, or scenarios where persistence is not required.
|
||||
///
|
||||
/// - **Temporary**: A temporary database on disk that is created for the duration of the
|
||||
/// connection and is automatically deleted when the connection is closed or when the
|
||||
/// process ends.
|
||||
///
|
||||
/// ### Usage
|
||||
///
|
||||
/// You can create instances of the `Location` enum to specify the desired database location:
|
||||
///
|
||||
/// ```swift
|
||||
/// let fileLocation = Connection.Location.file(path: "/path/to/database.db")
|
||||
/// let inMemoryLocation = Connection.Location.inMemory
|
||||
/// let temporaryLocation = Connection.Location.temporary
|
||||
/// ```
|
||||
/// Three locations are supported:
|
||||
/// - ``file(path:)``: A database at a specific file path or URI (persistent).
|
||||
/// - ``inMemory``: An in-memory database that exists only in RAM.
|
||||
/// - ``temporary``: A temporary on-disk database deleted when the connection closes.
|
||||
public enum Location {
|
||||
/// A database located at a given file path or URI.
|
||||
/// A database stored at a given file path or URI.
|
||||
///
|
||||
/// This case allows you to specify the exact location of a SQLite database using a file
|
||||
/// path or a URI. The provided path should point to a valid SQLite database file. If the
|
||||
/// database file does not exist, the behavior will depend on the connection options
|
||||
/// specified when opening the database.
|
||||
/// Use this for persistent databases located on disk or referenced via SQLite URI.
|
||||
/// The file is created if it does not exist (subject to open options).
|
||||
///
|
||||
/// - Parameter path: The path or URI to the database file. This can be an absolute or
|
||||
/// relative path, or a URI scheme supported by SQLite.
|
||||
///
|
||||
/// ### Example
|
||||
///
|
||||
/// You can create a `Location.file` case as follows:
|
||||
///
|
||||
/// ```swift
|
||||
/// let databaseLocation = Connection.Location.file(path: "/path/to/database.db")
|
||||
/// ```
|
||||
///
|
||||
/// - Important: Ensure that the specified path is correct and that your application has
|
||||
/// the necessary permissions to access the file.
|
||||
///
|
||||
/// For more details, refer to [Uniform Resource Identifiers](https://www.sqlite.org/uri.html).
|
||||
/// - Parameter path: Absolute/relative file path or URI.
|
||||
/// - SeeAlso: [Uniform Resource Identifiers](https://sqlite.org/uri.html)
|
||||
case file(path: String)
|
||||
|
||||
/// An in-memory database.
|
||||
/// A transient in-memory database.
|
||||
///
|
||||
/// In-memory databases are temporary and exist only in RAM. They are not persisted to disk,
|
||||
/// which makes them suitable for scenarios where you need fast access to data without the
|
||||
/// overhead of disk I/O.
|
||||
/// The database exists only in RAM and is discarded once the connection closes.
|
||||
/// Suitable for testing, caching, or temporary data processing.
|
||||
///
|
||||
/// When you create an in-memory database, it is stored entirely in memory, meaning that
|
||||
/// all data will be lost when the connection is closed or the application exits.
|
||||
///
|
||||
/// ### Usage
|
||||
///
|
||||
/// You can specify an in-memory database as follows:
|
||||
///
|
||||
/// ```swift
|
||||
/// let databaseLocation = Connection.Location.inMemory
|
||||
/// ```
|
||||
///
|
||||
/// - Important: In-memory databases should only be used for scenarios where persistence is
|
||||
/// not required, such as temporary data processing or testing.
|
||||
///
|
||||
/// - Note: In-memory databases can provide significantly faster performance compared to
|
||||
/// disk-based databases due to the absence of disk I/O operations.
|
||||
///
|
||||
/// For more details, refer to [In-Memory Databases](https://www.sqlite.org/inmemorydb.html).
|
||||
/// - SeeAlso: [In-Memory Databases](https://sqlite.org/inmemorydb.html)
|
||||
case inMemory
|
||||
|
||||
/// A temporary database on disk.
|
||||
/// A temporary on-disk database.
|
||||
///
|
||||
/// Temporary databases are created on disk but are not intended for persistent storage. They
|
||||
/// are automatically deleted when the connection is closed or when the process ends. This
|
||||
/// allows you to use a database for temporary operations without worrying about the overhead
|
||||
/// of file management.
|
||||
/// Created on disk and removed automatically when the connection closes or the
|
||||
/// process terminates. Useful for ephemeral data that should not persist.
|
||||
///
|
||||
/// Temporary databases can be useful for scenarios such as:
|
||||
/// - Testing database operations without affecting permanent data.
|
||||
/// - Storing transient data that only needs to be accessible during a session.
|
||||
///
|
||||
/// ### Usage
|
||||
///
|
||||
/// You can specify a temporary database as follows:
|
||||
///
|
||||
/// ```swift
|
||||
/// let databaseLocation = Connection.Location.temporary
|
||||
/// ```
|
||||
///
|
||||
/// - Important: Since temporary databases are deleted when the connection is closed, make
|
||||
/// sure to use this option only for non-persistent data requirements.
|
||||
///
|
||||
/// For more details, refer to [Temporary Databases](https://www.sqlite.org/inmemorydb.html).
|
||||
/// - SeeAlso: [Temporary Databases](https://sqlite.org/inmemorydb.html)
|
||||
case temporary
|
||||
|
||||
/// Returns the path to the database.
|
||||
///
|
||||
/// This computed property provides the appropriate path representation for the selected
|
||||
/// `Location` case. Depending on the case, it returns:
|
||||
/// - The specified file path for `.file`.
|
||||
/// - The string `":memory:"` for in-memory databases, indicating that the database exists
|
||||
/// only in RAM.
|
||||
/// - An empty string for temporary databases, as these are created on disk but do not
|
||||
/// require a specific file path.
|
||||
///
|
||||
/// ### Usage
|
||||
///
|
||||
/// You can access the `path` property as follows:
|
||||
///
|
||||
/// ```swift
|
||||
/// let location = Connection.Location.file(path: "/path/to/database.db")
|
||||
/// let databasePath = location.path // "/path/to/database.db"
|
||||
///
|
||||
/// let inMemoryLocation = Connection.Location.inMemory
|
||||
/// let inMemoryPath = inMemoryLocation.path // ":memory:"
|
||||
///
|
||||
/// let temporaryLocation = Connection.Location.temporary
|
||||
/// let temporaryPath = temporaryLocation.path // ""
|
||||
/// ```
|
||||
///
|
||||
/// - Note: When using the `.temporary` case, the returned value is an empty string
|
||||
/// because the database is created as a temporary file that does not have a
|
||||
/// persistent path.
|
||||
var path: String {
|
||||
switch self {
|
||||
case .file(let path): return path
|
||||
case .inMemory: return ":memory:"
|
||||
case .temporary: return ""
|
||||
case .file(let path): path
|
||||
case .inMemory: ":memory:"
|
||||
case .temporary: ""
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user