1 /** 2 DDBC - D DataBase Connector - abstraction layer for RDBMS access, with interface similar to JDBC. 3 4 Source file ddbc/package.d 5 6 DDBC library attempts to provide implementation independent interface to different databases. API is similar to Java JDBC API. 7 http://docs.oracle.com/javase/7/docs/technotes/guides/jdbc/ 8 9 For using DDBC, import this file: 10 11 12 import ddbc; 13 14 15 16 Supported (built-in) RDBMS drivers: MySQL, PostgreSQL, SQLite 17 18 Configuration name Version constants Drivers included 19 -------------------------- ---------------------------------- --------------------------------- 20 full USE_MYSQL, USE_SQLITE, USE_PGSQL mysql, sqlite, postgresql 21 MySQL USE_MYSQL mysql 22 SQLite USE_SQLITE sqlite 23 PGSQL USE_PGSQL postgresql 24 API (none) (no drivers, API only) 25 26 27 When using in DUB based project, add "ddbc" dependency to your project's dub.json: 28 29 "dependencies": { 30 "ddbc": "~>0.2.35" 31 } 32 33 Default configuration is "full". You can choose other configuration by specifying subConfiguration for ddbc, e.g.: 34 35 "subConfigurations": { 36 "ddbc": "SQLite" 37 } 38 39 40 If you want to support all DDBC configuration in your project, use configurations section: 41 42 "configurations": [ 43 { 44 "name": "default", 45 "subConfigurations": { 46 "ddbc": "full" 47 } 48 }, 49 { 50 "name": "MySQL", 51 "subConfigurations": { 52 "ddbc": "MySQL" 53 } 54 }, 55 { 56 "name": "SQLite", 57 "subConfigurations": { 58 "ddbc": "SQLite" 59 } 60 }, 61 { 62 "name": "PGSQL", 63 "subConfigurations": { 64 "ddbc": "PGSQL" 65 } 66 }, 67 { 68 "name": "API", 69 "subConfigurations": { 70 "ddbc": "API" 71 } 72 }, 73 ] 74 75 76 DDBC URLs 77 ========= 78 79 For creation of DDBC drivers or data sources, you can use DDBC URL. 80 81 Common form of DDBC URL: driver://host:port/dbname?param1=value1,param2=value2 82 83 As well, you can prefix url with "ddbc:" 84 ddbc:driver://host:port/dbname?param1=value1,param2=value2 85 86 Following helper function may be used to create URL 87 88 string makeDDBCUrl(string driverName, string host, int port, string dbName, string[string] params = null); 89 90 91 For PostgreSQL, use following form of URL: 92 93 postgresql://host:port/dbname 94 95 Optionally you can put user name, password, and ssl option as url parameters: 96 97 postgresql://host:port/dbname?user=username,password=userpassword,ssl=true 98 99 100 For MySQL, use following form of URL: 101 102 mysql://host:port/dbname 103 104 Optionally you can put user name and password as url parameters: 105 106 mysql://host:port/dbname?user=username,password=userpassword 107 108 109 For SQLite, use following form of URL: 110 111 sqlite:db_file_path_name 112 113 Sample urls: 114 115 string pgsqlurl = "postgresql://localhost:5432/ddbctestdb?user=ddbctest,password=ddbctestpass,ssl=true"; 116 string mysqlurl = "mysql://localhost:3306/ddbctestdb?user=ddbctest,password=ddbctestpass"; 117 string sqliteurl = "sqlite:testdb.sqlite"; 118 119 120 Drivers, connections, data sources and connection pools. 121 ======================================================= 122 123 124 Driver - factory interface for DB connections. This interface implements single method to create connections: 125 126 Connection connect(string url, string[string] params); 127 128 DataSource - factory interface for creating connections to specific DB instance, holds enough information to create connection using simple call of getConnection() 129 130 ConnectionPool - DataSource which implements pool of opened connections to avoid slow connection establishment. It keeps several connections opened in pool. 131 132 Connection - main object for dealing with DB. 133 134 135 Driver may be created using one of factory methods: 136 137 /// create driver by name, e.g. "mysql", "postgresql", "sqlite" 138 DriverFactory.createDriver(string driverName); 139 /// create driver by url, e.g. "mysql://host:port/db", "postgresql://host:port/db", "sqlite://" 140 DriverFactory.createDriverForURL(string url); 141 142 143 There are helper functions to create Connection, DataSource or ConnectionPool from URL and parameters. 144 145 /// Helper function to create DDBC connection, automatically selecting driver based on URL 146 Connection createConnection(string url, string[string]params = null); 147 148 /// Helper function to create simple DDBC DataSource, automatically selecting driver based on URL 149 DataSource createDataSource(string url, string[string]params = null); 150 151 /// Helper function to create connection pool data source, automatically selecting driver based on URL 152 DataSource createConnectionPool(string url, string[string]params = null, int maxPoolSize = 1, int timeToLive = 600, int waitTimeOut = 30); 153 154 155 If you are planning to create several connections, consider using DataSource or ConnectionPool. 156 157 For simple cases, it's enough to create connection directly. 158 159 Connection conn = createConnection("sqlite:testfile.sqlite"); 160 161 If you need to get / release connection multiple times, it makes sense to use ConnectionPool 162 163 DataSource ds = createConnectionPool("ddbc:postgresql://localhost:5432/ddbctestdb?user=ddbctest,password=ddbctestpass,ssl=true"); 164 // now we can take connection from pool when needed 165 auto conn = ds.getConnection(); 166 // and then release it back to pool when no more needed 167 conn.close(); 168 // if we call ds.getConnection() one more time, existing connection from pool will be used 169 170 171 Copyright: Copyright 2014 172 License: $(LINK www.boost.org/LICENSE_1_0.txt, Boost License 1.0). 173 Author: Vadim Lopatin 174 */ 175 module ddbc; 176 177 public import ddbc.core; 178 public import ddbc.common; 179 public import ddbc.pods; 180 181 version( USE_SQLITE ) 182 { 183 // register SQLite driver 184 private import ddbc.drivers.sqliteddbc; 185 } 186 version( USE_PGSQL ) 187 { 188 // register Postgres driver 189 private import ddbc.drivers.pgsqlddbc; 190 } 191 version(USE_MYSQL) 192 { 193 // register MySQL driver 194 private import ddbc.drivers.mysqlddbc; 195 }